The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Subscriptions Export

Subscriptions v3

Version Created: 5/2/19
Version updates Summary

  • Column added for Shipping Cost
  • Column added for Shipping Method

Subscriptions v2

Version created - 9/6/18
Version updates Summary

  • 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

Subscriptions

This export identifies accounts that have a subscription stored, with all the relevant subscription details.

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.

Time Range Filter

Activated

Subscriptions that were activated during the selected time range. Represented in the "Activated_at" column of the export

Modified

Subscriptions that were modified during the selected time range. Represented in the "modified_at" column of the export.

Created

Subscriptions that were created during the selected time range. Represented in 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,
test@example.com

Account associated with a given subscription UUID.

email

test@example.com

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).

Subscriptions - Churned

Subscriptions - Churned v2

Version Created: 5/2/19
Version updates Summary

  • Column added for Shipping Cost
  • Column added for Shipping Method

This export identifies subscriptions that have churned and are no longer active.

Time Range Filter

Uses the "expired_at" column. Exports subscriptions that expired during the selected time range.

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, test@example.com

Account associated with a given subscription UUID.

email

test@example.com

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

jsmith@example.com

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.

Subscriptions Export


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.