Subscriptions Exports
Recurly offers two different exports for subscriptions, one containing all active subscriptions and one containing subscriptions that have churned and are no longer active.
Subscriptions
This export identifies accounts that have a subscription stored, with all the relevant subscription details.
Version Change Log
Version 4 - 12/7/2021
- Column added for pricing_model
- Column added for current_ramp_id
Version 3 - 5/2/2019
- Column added for Shipping Cost
- Column added for Shipping Method
Version 2 - 9/6/2018
- Column additions for Custom Fields
- Each Custom Field will be added as the last column in the export
- The name of the column will begin with "custom_field" and append the API name to the end
- Custom fields will only be included at the end of the export if the setting for exports is enabled on the custom field definition
Subscription Status Filter
Live
All active subscriptions.
Renewing
Live subscriptions that will renew after the current term.
Trial
Live subscriptions that are in a trial period.
Paused
Live subscriptions that are currently paused.
Canceled
Live subscriptions that will not renew after the current term.
Past Due
Live subscriptions with a past-due invoice.
Future
Subscriptions that will become active when the start date arrives.
Expired
Inactive subscriptions.
Failed
This status refers to subscriptions that were never created due to a failed credit card validation. This status can also refer to a future subscription that is terminated prior to its start_date.
Date Range Filters
Activated
Subscriptions that were activated during the selected time range. Uses in the "activated_at" column of the export.
Modified
Subscriptions that were modified during the selected time range. Uses in the "modified_at" column of the export. You will only see the subscription modified- original subscription will not show when using export on modified parameter.
Created
Subscriptions that were created during the selected time range. Uses the "created_at" column of the export. This option will include subscriptions that have been created but have a future activation date.
Export Contents
| Column Name | Example | Description |
|---|---|---|
| uuid | b964b5439c2548a489 | Unique internal identifier for the subscription. Even if a subscription is modified, this identifier is maintained. |
| account_code | 123456789, [email protected] | Account associated with a given subscription UUID. |
| [email protected] | Email address associated with a given subscription UUID. | |
| plan_code | basic | Plan that the customer is subscribed to with this UUID. |
| state | pending, active, canceled, expired | Current state of the subscription. |
| auto_renew | TRUE, FALSE | Defaults to TRUE for auto-renewing subscriptions. FALSE if subscription configured to expire at the end of the current term. |
| currency | USD | Identifies the currency being charged with this subscription. |
| quantity | 1 | Identifies the quantity of the subscription purchase. |
| unit_amount | 99 | Identifies the base price of 1 quantity of the subscription |
| add_on_amount | 15 | Identifies any additional charges to the subscription base fee from add_ons. |
| total_recurring_amount | 114 | Identifies total recurring charges - unit_amount x quantity + add_on_amount. |
| current_period_started_at | 2009-12-04 00:46:59 PST | Date and time that the current billing period starts at. |
| current_period_ends_at | 2009-01-04 00:46:59 PST | Date and time that the current billing period ends at |
| trial_started_at | 2010-03-24 17:18:46 PDT | Date and time that a trial period began on the subscription. |
| trial_ends_at | 2010-04-23 17:18:46 PDT | Date and time that a trial period ends on the subscription. |
| total_billing_cycles | 1 | This is the total number of billing periods in the current term. |
| remaining_billing_cycles | 0 | This is the remaining number of billing periods remaining in the subscription term that will bill. Always 0 for subscriptions with a single billing period term set to auto_renew=true |
| activated_at | 2010-03-24 17:18:46 PDT | Date and time the subscription became active on an account. This might not match to the subscription_created_at date if the subscription is added with a future start date. |
| modified_at | 2010-03-24 17:18:44 PDT | Date and time the subscription was last updated. |
| canceled_at | 2010-03-28 22:54:46 PDT | Date and time the subscription was canceled. |
| expires_at | 2010-04-23 22:51:53 PDT | Date and time the subscription was/ will churn. This field is populated when a subscription cancels with the expected expiration date. |
| maintenance_url | app.recurly.com/account/sdasdasdad | Link to the customer's hosted account maintenance URL. |
| net_terms | on-receipt | Identifies the net_terms agreement associated with the subscription. |
| po_number | 213123 | For manual invoicing, this identifies the PO number associated with the subscription. |
| collection_method | automatic/manual | Identifies whether the subscription fees are collected via manual or automatic invoicing. |
| plan_name | Gold | The name of the plan associated with the subscription. This is the current name of the plan. |
| started_with_gift | TRUE, FALSE | TRUE` if the subscription was started with a gift card, whether or not billing information was collected. |
| converted_at | 2016-09-02 15:53:18 UTC | Date of the first successful transaction for the subscription. This field is only used for gifts cards and cardless free trial conversions. In other words, it will only have a value if started_with_gift is TRUE OR no_billing_info_reason is "plan_free"trial." Converted_at compared to the subscription's activated_at will give you the time to conversion. |
| no_billing_info_reason | plan_free_trial | Identifies the reason why a subscription did not have billing information at time of renewal/activation. |
| paused_at | 2018-05-13 00:00:12 MDT | Date of when the subscription was paused or is scheduled to pause. |
| remaining_pause_cycles | 9 | Identifies the number of remaining billing cycles for the subscription that is either currently paused or scheduled to pause. |
| current_term_started_at | 2018-12-04 00:46:59 PST | Date and time that the current term started at. This currently is an unpopulated field relating to an upcoming feature which will be released later this year. |
| current_term_ends_at | 2019-12-04 00:46:59 PST | Date and time that the current term ends at. This currently is an unpopulated field relating to an upcoming feature which will be released later this year. |
| renewal_billing_cycles | 1 | The length of a subscription's next term, if auto_renew = true NIL if subscription auto_renew = false |
| shipping_amount_in_cents | 500 | The shipping fee on the subscription, in cents. |
| shipping_method_code | usps-overnight | The code from the shipping method (created through the UI). |
| pricing_model | ramp | Pricing model of the subscription. Will be either fixed or ramp. |
| current_ramp_id | pz82514rbd3s | The id of the current ramp interval. |
| tax_inclusive | true | Indicates whether the subscription is billed inclusively or exclusively of tax. |
| custom_field(customfieldAPIname) | subid_1234abcd | The value of the custom field. |
Subscriptions - Churned
This export identifies subscriptions that have churned and are no longer active.
Version Change Log
Version 3 - 12/7/2021
- Column added for pricing_model
- Column added for current_ramp_id
Version 2 - 5/2/2019
- Column added for Shipping Cost
- Column added for Shipping Method
Time Range Filter
Exports all subscriptions that expired during the selected time range. Uses the "expired_at" column in the export.
Please note that the "canceled_at" and "expired_at" dates are not the same. A subscription does not churn until the subscription has expired.
Export Contents
| Column Name | Example | Description |
|---|---|---|
| uuid | 5eg5bcc7ef8211e0a908005056b00005 | Unique identifier for a specific subscription plan. |
| account_code | 123456789, [email protected] | Account associated with a given subscription UUID. |
| [email protected] | Email address associated with a given subscription UUID. | |
| plan_code | basic | Plan that the customer is subscribed to with this UUID. |
| state | pending, modified, converted, active, canceled, expired | Current state of the subscription. Modified and converted are depreciated states |
| auto_renew | TRUE | Defaults to TRUE for auto-renewing subscriptions. FALSE if subscription set to expire at end of current term. |
| currency | USD | Identifies the currency being charged with this subscription. |
| quantity | 1 | Identifies the quantity of the subscription purchase. |
| unit_amount | 99 | Identifies the base price of 1 quantity of the subscription. |
| add_on_amount | 15 | Identifies any additional charges to the subscription base fee from add_ons. |
| total_recurring_amount | 114 | Identifies total recurring charges - unit_amount x quantity + add_on_amount. |
| current_period_started_at | 2009-12-04 00:46:59 PST | Date and time that the current billing period started. * |
| current_period_ends_at | 2009-12-04 00:46:59 PST | Date and time that the current billing period ends at. |
| trial_started_at | 2010-03-24 17:18:46 PDT | Date and time that a trial period began on the subscription. |
| trial_ends_at | 2010-04-23 17:18:46 PDT | Date and time that a trial period ends on the subscription. |
| total_billing_cycles | 1 | This is the total number billing periods in the subscription term. |
| remaining_billing_cycles | 0 | Number of remaining billing periods in the subscription’s current term. Will always be 0 if subscription term has 1 billing period |
| renewal_billing_cycles | 1 | Number of billing periods in the subscription’s next term. Will default to plan’s total_billing_cycles unless customized. Nil if auto_renew = false |
| current_term_started_at | 2018-09-02 15:53:18 UTC | Start date of the subscription’s current term |
| current_term_ends_at | 2018-10-02 15:53:18 UTC | End date of the subscription’s current term. |
| activated_at | 2010-03-24 17:18:46 PDT | Date and time the subscription was added to the account. |
| modified_at | 2010-03-24 17:18:44 PDT | Date and time the subscription was last updated. |
| canceled_at | 2010-03-28 22:54:46 PDT | Date and time the subscription was canceled. |
| expires_at | 2010-04-23 22:51:53 PDT | Date and time the subscription was terminated. Used for date range filter |
| maintenance_url | app.recurly.com/account/sdasdasdad213525asdad | Link to the customer's hosted account maintenance URL. |
| net_terms | on-receipt | Identifies the net_terms agreement associated with the subscription. |
| po_number | 213123 | For manual invoicing, this identifies the PO number associated with the subscription. |
| collection_method | automatic/manual | Identifies whether the subscription fees are collected via manual or automatic invoicing |
| plan_name | Basic Plan | The plan name of the subscription at the time the subscription expired |
| expiration_reason | Canceled, Non-payment, Fixed billing cycles, Tax Location Invalid, Nonpayment_gift, Nonpayment_trial | The reason that the subscription expired. Note that nonpayment_Trial only relates to cardless subscriptions trials |
| ship_address_id | 2019760433389770000 | The unique ID assigned to the shipping address |
| ship_address_nickname | Julie | The nickname given to the shipping address |
| ship_address_firstname | Julie | The first name associated with the shipping address |
| ship_address_lastname | Smith | The last name associated with the shipping address |
| ship_address_company_name | Big Company | The company name associated with the shipping address |
| ship_address_street1 | 321 Michigan Street | The first line of the street address for the shipping address |
| ship_address_street2 | Apt 1 | The second line of the street address for the shipping address |
| ship_address_city | West Bloomfield | The city for the shipping address |
| ship_address_state | MI | The state for the shipping address |
| ship_address_zip | 48322 | The zip or postal code for the shipping address |
| ship_address_country | US | The country for the shipping address |
| ship_address_vat | 123456789 | The VAT number associated with the shipping address |
| ship_address_email | [email protected] | The email address associated with the shipping address |
| ship_address_phone | 248-555-1212 | The phone number associated with the shipping address |
| started_with_gift | TRUE, FALSE | TRUE if the subscription was started with a gift card, whether or not billing information was collected. |
| converted_at | 2016-09-02 15:53:18 UTC | Date of the first successful transaction for the subscription. This field is only used for gifts cards and cardless free trial conversions. In other words, it will only have a value if started_with_gift is TRUE OR no_billing_info_reason is "plan_free"trial." Converted_at compared to the subscription's activated_at will give you the time to conversion. |
| no_billing_info_reason | plan_free_trial | Identifies the reason why a subscription did not have billing information at time of renewal/activation. |
| shipping_amount_in_cents | 500 | The amount of the shipping fee on the subscription, in cents. |
| shipping_method_code | usps_overnight | The code of the Shipping Method from configuration. |
| pricing_model | ramp | Pricing model of the subscription. Will be either fixed or ramp. |
| current_ramp_id | pz82514rbd3s | The id of the current ramp interval. |
Updated 7 months ago