Subscription add-ons — history
Delve into the rich history of your subscription add-ons and leverage valuable insights with our detailed export feature in the "Subscription Add-ons — History" section.
Overview
Required plan
This feature or setting is available to all customers on any Recurly subscription plan.
Prerequisites
Please reach out to your Recurly account manager or [email protected] to have this feature activated in your account.
Definition
Explore the subscription add-on history feature that allows tracking all the changes made to a subscription add-on over time. Every time a change or multiple changes are made simultaneously, a new version of the subscription add-on history is created. This feature is vital for keeping historical versions of add-ons that change on subscriptions.
Filters
Subscription Status Filter
- All: Displays all subscription history status.
- Trial: Displays all subscription history respective to trial status.
- Open: Displays all subscription history respective to open status.
- Canceled: Displays all subscription history respective to canceled status.
- Expired: Displays all subscription history respective to expired status.
Date Range Filters
Activated
Showcases the past versions of subscription add-ons that were activated or reactivated within the chosen time frame. It utilizes the subscription_activated_at column for data representation.
Created
Depicts the past versions of subscription add-ons generated during a specified time range, utilizing data from the version_started_at column.
Modified
View recent alterations to all subscriptions within a chosen time range, referring to a combination of version_state and version_started_at columns.
Exports table
To help you identify and organize information effectively, the export provides a structured table that contains the following columns:
| Column Name | Example | Description | Data type (max size) |
|---|---|---|---|
| subscription_uuid | 434f11do8b297982eb | Unique internal identifier for the subscription. Even if a subscription is modified, this identifier is maintained. | varchar(32) |
| version_uuid | 43509049eb30fb | Unique 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. | string |
| account_code | 123456789, [email protected] | Account associated with a given subscription_uuid. | varchar(50) |
| subscription_activated_at | 2018-03-24 17:18:46 PDT | Date and time the subscription became active (or reactivated) on an account. Note that this might not always match exactly with the subscription_created_At date if a subscription is created with a future start date. | timestamp |
| subscription_expires_at | 2018-09-24 17:18:46 PDT | Date and time the subscription was/ will churn. This field is populated when a subscription cancels with the expected expiration date. | timestamp |
| subscription_state | active, canceled, paused, expired | State of the subscription at the time the version was active. | string |
| version_started_at | 2018-03-20 03:22:25 EST | The date a change was made to the subscription and thus the new version was created. | timestamp |
| version_ended_at | 2018-07-20 03:22:25 EST | The 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. | timestamp |
| version_state | inactive or active | the 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" | string |
| plan_code | bronze_1 | the plan that the subscription was actively on while that version was active. Codes are used internally only. | varchar(50) |
| plan_name | Bronze Plan # 1 | The name of the plan the subscriber was actively on while that version was active. | varchar(25) |
| subscription_currency | USD, GBP, CAD | The currency associated with that subscription at the time that version was active | varchar(3) |
| version_plan_interval_unit | months, weeks, days, years | The 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. | varchar(10) |
| version_plan_interval_length | any number | The 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 | numeric(10) |
| version_collection_method | automatic, manual | Identifies whether the subscription fees are collected via manual or automatic invoicing. | string |
| version_total_billing_cycles | 1 | If 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. | numeric |
| version_subscription_quantity | 1, 2 | Identifies the quantity of the subscription purchase at the time the version was active. | numeric |
| version_subscription_unit_amount | 100 | Identifies the base price of 1 quantity of the subscription at the time the version was active. | numeric |
| version_add_on_code | add_on1, add_on1, add_on2 | A 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. | varchar(50) |
| version_add_on_quantity | 1 | Identifies the quantity of the add-on at the time the version was active. | numeric |
| version_add_on_type | fixed, fixed, usage | Lists the type of add_on in corresponding order to the listed add_on_codes on the subscription at the time the version was active. | string |
| version_add_on_unit_amount | 10, 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 | numeric |
| version_add_ons_total | 20 | Sums the add_on_unit_amounts on the subscription at the time the version was active. Does not include usage based add ons. | numeric |
| version_total_recurring_amount | 120 | (version_unit_amount) * (version_subscription_quantity) + version_add_on_total | numeric |
| version_in_trial | Y, N | Indicates whether or not the subscription was in trial while the version was active. | boolean |
| version_auto_renew | Y, N | Indicates whether or not the subscription was set to auto renew while the version was active. | boolean |
| version_renewal_billing_cycles | 1 | Indicated the number of billing cycles a subscription will have after the end of the subscription term. | numeric |
| external_sku | 093094f0420 | - | varchar(50) |
| version_add_on_tier_type | flat, tiered, volume, stairstep | The pricing model used to calculate the costs for the subscriptions based on the quantity purchased. | string |
| version_add_on_source | - | - | string |
| version_add_on_unit_amount_decimal | - | - | numeric |
| version_add_on_billing_model | - | - | string |
Version changelog
Version 2 -3/9/2022
- Introduced a new column version_add_on_billing_model.
Version 4 - 1/22/2021
- Introduced a new column version_add_on_unit_amount_decimal.
Version 3 - 6/23/2020
- Introduced a new column version_add_on_source.
Version 2 - 4/2/2020
- Introduced a new column for external SKU concerning saved item add-ons.
- Introduced a new column version_add_on_tier_type.
Updated 22 days ago