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 NameExampleDescription
uuidb964b5439c2548a489Unique internal identifier for the subscription. Even if a subscription is modified, this identifier is maintained.
account_code123456789,
[email protected]
Account associated with a given subscription UUID.
email[email protected]Email address associated with a given subscription UUID.
plan_codebasicPlan that the customer is subscribed to with this UUID.
statepending, active, canceled, expiredCurrent state of the subscription.
auto_renewTRUE, FALSEDefaults to TRUE for auto-renewing subscriptions. FALSE if subscription configured to expire at the end of the current term.
currencyUSDIdentifies the currency being charged with this subscription.
quantity1Identifies the quantity of the subscription purchase.
unit_amount99Identifies the base price of 1 quantity of the subscription
add_on_amount15Identifies any additional charges to the subscription base fee from add_ons.
total_recurring_amount114Identifies total recurring charges - unit_amount x quantity + add_on_amount.
current_period_started_at2009-12-04 00:46:59 PSTDate and time that the current billing period starts at.
current_period_ends_at2009-01-04 00:46:59 PSTDate and time that the current billing period ends at
trial_started_at2010-03-24 17:18:46 PDTDate and time that a trial period began on the subscription.
trial_ends_at2010-04-23 17:18:46 PDTDate and time that a trial period ends on the subscription.
total_billing_cycles1This is the total number of billing periods in the current term.
remaining_billing_cycles0This 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_at2010-03-24 17:18:46 PDTDate 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_at2010-03-24 17:18:44 PDTDate and time the subscription was last updated.
canceled_at2010-03-28 22:54:46 PDTDate and time the subscription was canceled.
expires_at2010-04-23 22:51:53 PDTDate and time the subscription was/ will churn.

This field is populated when a subscription cancels with the expected expiration date.
maintenance_urlapp.recurly.com/account/sdasdasdadLink to the customer's hosted account maintenance URL.
net_termson-receiptIdentifies the net_terms agreement associated with the subscription.
po_number213123For manual invoicing, this identifies the PO number associated with the subscription.
collection_methodautomatic/manualIdentifies whether the subscription fees are collected via manual or automatic invoicing.
plan_nameGoldThe name of the plan associated with the subscription. This is the current name of the plan.
started_with_giftTRUE, FALSETRUE` if the subscription was started with a gift card, whether or not billing information was collected.
converted_at2016-09-02 15:53:18 UTCDate 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_reasonplan_free_trialIdentifies the reason why a subscription did not have billing information at time of renewal/activation.
paused_at2018-05-13 00:00:12 MDTDate of when the subscription was paused or is scheduled to pause.
remaining_pause_cycles9Identifies the number of remaining billing cycles for the subscription that is either currently paused or scheduled to pause.
current_term_started_at2018-12-04 00:46:59 PSTDate 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_at2019-12-04 00:46:59 PSTDate 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_cycles1The length of a subscription's next term, if auto_renew = true

NIL if subscription auto_renew = false
shipping_amount_in_cents500The shipping fee on the subscription, in cents.
shipping_method_codeusps-overnightThe code from the shipping method (created through the UI).
pricing_modelrampPricing model of the subscription. Will be either fixed or ramp.
current_ramp_idpz82514rbd3sThe id of the current ramp interval.
tax_inclusivetrueIndicates whether the subscription is billed inclusively or exclusively of tax.
custom_field(customfieldAPIname)subid_1234abcdThe 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 NameExampleDescription
uuid5eg5bcc7ef8211e0a908005056b00005Unique identifier for a specific subscription plan.
account_code123456789, [email protected]Account associated with a given subscription UUID.
email[email protected]Email address associated with a given subscription UUID.
plan_codebasicPlan that the customer is subscribed to with this UUID.
statepending, modified, converted, active, canceled, expiredCurrent state of the subscription. Modified and converted are depreciated states
auto_renewTRUEDefaults to TRUE for auto-renewing subscriptions. FALSE if subscription set to expire at end of current term.
currencyUSDIdentifies the currency being charged with this subscription.
quantity1Identifies the quantity of the subscription purchase.
unit_amount99Identifies the base price of 1 quantity of the subscription.
add_on_amount15Identifies any additional charges to the subscription base fee from add_ons.
total_recurring_amount114Identifies total recurring charges - unit_amount x quantity + add_on_amount.
current_period_started_at2009-12-04 00:46:59 PSTDate and time that the current billing period started. *
current_period_ends_at2009-12-04 00:46:59 PSTDate and time that the current billing period ends at.
trial_started_at2010-03-24 17:18:46 PDTDate and time that a trial period began on the subscription.
trial_ends_at2010-04-23 17:18:46 PDTDate and time that a trial period ends on the subscription.
total_billing_cycles1This is the total number billing periods in the subscription term.
remaining_billing_cycles0Number of remaining billing periods in the subscription’s current term. Will always be 0 if subscription term has 1 billing period
renewal_billing_cycles1Number 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_at2018-09-02 15:53:18 UTCStart date of the subscription’s current term
current_term_ends_at2018-10-02 15:53:18 UTCEnd date of the subscription’s current term.
activated_at2010-03-24 17:18:46 PDTDate and time the subscription was added to the account.
modified_at2010-03-24 17:18:44 PDTDate and time the subscription was last updated.
canceled_at2010-03-28 22:54:46 PDTDate and time the subscription was canceled.
expires_at2010-04-23 22:51:53 PDTDate and time the subscription was terminated. Used for date range filter
maintenance_urlapp.recurly.com/account/sdasdasdad213525asdadLink to the customer's hosted account maintenance URL.
net_termson-receiptIdentifies the net_terms agreement associated with the subscription.
po_number213123For manual invoicing, this identifies the PO number associated with the subscription.
collection_methodautomatic/manualIdentifies whether the subscription fees are collected via manual or automatic invoicing
plan_nameBasic PlanThe plan name of the subscription at the time the subscription expired
expiration_reasonCanceled, Non-payment, Fixed billing cycles, Tax Location Invalid, Nonpayment_gift, Nonpayment_trialThe reason that the subscription expired. Note that nonpayment_Trial only relates to cardless subscriptions trials
ship_address_id2019760433389770000The unique ID assigned to the shipping address
ship_address_nicknameJulieThe nickname given to the shipping address
ship_address_firstnameJulieThe first name associated with the shipping address
ship_address_lastnameSmithThe last name associated with the shipping address
ship_address_company_nameBig CompanyThe company name associated with the shipping address
ship_address_street1321 Michigan StreetThe first line of the street address for the shipping address
ship_address_street2Apt 1The second line of the street address for the shipping address
ship_address_cityWest BloomfieldThe city for the shipping address
ship_address_stateMIThe state for the shipping address
ship_address_zip48322The zip or postal code for the shipping address
ship_address_countryUSThe country for the shipping address
ship_address_vat123456789The VAT number associated with the shipping address
ship_address_email[email protected]The email address associated with the shipping address
ship_address_phone248-555-1212The phone number associated with the shipping address
started_with_giftTRUE, FALSETRUE if the subscription was started with a gift card, whether or not billing information was collected.
converted_at2016-09-02 15:53:18 UTCDate 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_reasonplan_free_trialIdentifies the reason why a subscription did not have billing information at time of renewal/activation.
shipping_amount_in_cents500The amount of the shipping fee on the subscription, in cents.
shipping_method_codeusps_overnightThe code of the Shipping Method from configuration.
pricing_modelrampPricing model of the subscription. Will be either fixed or ramp.
current_ramp_idpz82514rbd3sThe id of the current ramp interval.