Subscriptions — History Export

View the history for each subscription. Every time a change (or multiple changes at the same time) is made to a subscription, a new version of that subscription is created. This enables you to track historic versions of subscriptions in order to track important movements in your subscriber's lifecycle, such as upgrades, downgrades, cancellations, trial conversions, etc.

The following changes will create a new version of the subscription:

  • Plan changes
  • Quantity changes
  • Price changes (upgrade or downgrade)
  • State changes including active, paused, canceled and expired states
  • Trial ends
  • Collection method changes
  • Total billing cycles changes

The subscription history export only tracks changes after a subscription has been activated.

📘

Please reach out to [email protected] if you'd like this export to be enabled for your site.

Version Change Log

Version 5 - 12/7/2021

  • Column added for pricing_model
  • Column added for current_ramp_id

Version 4

  • Updated the following columns remove any concatenated: version_add_on_codes, version_add_on_types, version_add_on_unit_amounts

Version 3

  • Added new column: version_add_on_tier_types

Version 2 - 1/9/2020

  • Columns added for shipping method and shipping amount

Date Range Filters

Activated

This filter is useful for viewing past subscription versions of subscriptions activated/ reactivated in the specified time range. Uses the subscription_activated_at column.

Created

Returns all versions created in the specified time range. This filter is useful for viewing recent changes to all subscriptions. Uses the version_created_at column.

Export Contents

Column NameExampleDescription
subscription_uuid434f11do8b297982ebUnique internal identifier for the subscription. Even if a subscription is modified, this identifier is maintained.
version_uuid43509049eb30fbUnique internal identifier for the version of a subscription_uuid.
A new version if created when a change is made to a subscription. If multiple different changes are made at the same time, all will be captured in the same new version.
account_code123456789,
[email protected]
Account associated with a given subscription_uuid.
subscription_activated_at2018-03-24 17:18:46 PDTDate and time the subscription became active (or reactivated) on an account.
subscription_expires_at2018-09-24 17:18:46 PDTDate and time the subscription was/ will churn.

This field is populated when a subscription cancels with the expected expiration date.
subscription_stateactive, canceled, paused,
expired
State of the subscription at the time the version was active.
version_started_at2018-03-20 03:22:25 ESTThe date a change was made to the subscription and thus the new version was created.
version_ended_at2018-07-20 03:22:25 ESTThe date a version is no longer active because another change to the subscription is a made and a newer version is created.
All versions with the version_state of "inactive" will have a version_expired_at date.
version_stateinactive or activethe versions of a subscription that reflect the current attributes of that subscription (i.e are currently in use) are "active." All expired versions are "inactive"
plan_codebronze_1the plan that the subscription was actively on while that version was active. Codes are used internally only.
plan_nameBronze Plan # 1The name of the plan the subscriber was actively on while that version was active.
subscription_currencyUSD, GBP, CADThe currency associated with that subscription at the time that version was active
version_plan_interval_unitmonths, weeks, days, yearsThe interval type at which that subscription is billed while that version was active. Combined with the version_plan_internval_length, you can understand how often your customer is billed
example: 1 month, 2 months, 1 year, etc.
version_plan_interval_lengthany numberThe length of the interval type at which the subscription is billed at while the version was active.
Example: 1 month, 2 months, 1 year ,etc
version_collection_methodautomatic, manualIdentifies whether the subscription fees are collected via manual or automatic invoicing.
version_total_billing_cycles1If configured on the plan, the total number of bill cycles that the subscription will bill at the time the version was active.
If not specifically configured, the subscription will auto renew and this field will be blank.
version_subscription_quantity1, 2Identifies the quantity of the subscription purchase at the time the version was active.
version_subscription_unit_amount100Identifies the base price of 1 quantity of the subscription at the time the version was active.
version_add_on_codesadd_on1, add_on1, add_on2A list of add ons that were active on the subscription at the time the version was active.
If there is more than one of the same add_on, it will be listed the same number of times as the quantity.
version_add_on_typesfixed, fixed, usageLists the type of add_on in corresponding order to the listed add_on_codes on the subscription at the time the version was active.
version_add_on_unit_amounts10, 10, 5%Lists the unit amount of the add_on in corresponding order to the listed add_on_codes and listed add_on_types.
If the add_on_type is "usage" the "%" will be listed
version_add_ons_total20Sums the add_on_unit_amounts on the subscription at the time the version was active.
Does not include usage based add ons.
version_total_recurring_amount120(version_unit_amount) * (version_subscription_quantity) + version_add_on_total
version_in_trialY, NIndicates whether or not the subscription was in trial while the version was active.
version_auto_renewY, NIndicates whether or not the subscription was set to auto renew while the version was active.
version_renewal_billing_cycles1
version_shipping_method_nameUSPS OvernightThe shipping method name used at the time when the version was active.
version_shipping_amount5Identifies the shipping price on the subscription at the time the version was active.
pricing_modelrampPricing model of the subscription. Will be either fixed or ramp.
current_ramp_idpz82514rbd3sThe id of the current ramp interval.