Toolkit CSV reference
Follow best practices to successfully migrate your subscriptions using the no-code Billing migration toolkit.
Use this guide to help you specify your CSV file in the Billing migration toolkit. In the following examples, all timestamps are in Unix EPOCH format. We also provide test customer and price IDs that you can use while in test mode.
CSV prerequisites![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Before you create or download a CSV file, make sure you know the following:
Customer object | All customers must have a default payment method attached to them. Without a default payment method, future subscription payments will fail. If you don’t have a default payment method set for your customers after migrating their data, you have two options:
|
Automatic tax | If you use Stripe Tax (where you set automatic tax to true), all customers must have either addresses or postal codes (or both) per country. Stripe needs this information to calculate taxes for the given subscriptions. |
collection_method | If you’re using the send_ payment method for your subscriptions:
|
Dates |
|
Coupons |
|
Stripe to Stripe migration | Users can migrate subscriptions within Stripe accounts. You must input Customer IDs and Price IDs (and both Coupon IDs and Tax IDs, if using them) into the template associated with your destination Stripe account, and not your source Stripe account. The migration tool generates an error if you input IDs associated with your source account. |
Migration use-cases![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
You can apply the following migration use cases to your own migration, if applicable:
- Migrate subscriptions with various pricing models
- Migrate subscriptions with different types of payment collection methods
- Migrate subscriptions at different stages of the subscription cycle
- Migrate subscriptions with taxes
- Migrate subscriptions with discounts
- Migrate subscriptions within Stripe accounts
- Migrate subscriptions with multiple phases
You can combine any Stripe-provided CSV template (Basic, Multi-price items, Ad-hoc pricing) with any of the examples below as needed.
Migrate subscriptions with various pricing models![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
You can migrate subscriptions with flat-rate pricing, such as a basic plan at 100 USD per month or an advanced plan at 200 USD per month. These subscriptions can have one or more line items.
Example 1 (Basic): Migrate a basic 100 USD monthly subscription with a quantity of 2, starting on 1 January 2024. The subscription is charged automatically using the default payment method.
ATTRIBUTE | customer (required) | start_date (required) | price (required) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
FIELD | cus_xxxx1 | 1704067200 | price_xxx1 | 2 | subscription_1 | none | charge_automatically |
Example 2 (Multi-price items): Migrate the following subscriptions starting on 1 January 2024, to be charged automatically using the default payment method:
- A basic 100 USD monthly subscription with a quantity of 2
- An advanced 200 USD monthly subscription with a quantity of 1
ATTRIBUTE | customer (required) | start_date (required) | items.0.price (required) | items.0.quantity | items.1.price | items.1.quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency | |
FIELD | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | price_xxx2 | subscription_1 | none | charge_automatically |
Example 3 (Basic): Migrate the following subscription starting on 1 January 2024, to be charged automatically using the default payment method:
- A basic 100 USD monthly subscription with a quantity of 2
- An ad-hoc invoice add-on fee of 20 USD
ATTRIBUTE | customer (required) | start_date (required) | price (required) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
FIELD | cus_xxxx1 | 1704067200 | price_xxx1 | 2 | subscription_1 | none | charge_automatically | 50 | prod_xxx1 | usd |
You can also migrate subscriptions with ad-hoc pricing, in cases where you don’t have fixed pricing amounts.
Example 4 (Ad-hoc pricing): Migrate the following subscription starting on 1 January 2024, to be charged automatically using the default payment method:
- A 153 USD ad-hoc monthly subscription with a quantity of 1
ATTRIBUTE | customer (required) | start_date (required) | adhoc_items.0.amount (required) | adhoc_items.0.product | adhoc_items.0.interval | adhoc_items.0.currency | adhoc_items.0.quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
FIELD | cus_xxxx1 | 1704067200 | price_xxx1 | prod_xxx1 | 1 | subscription_1 | none | charge_automatically |
Migrate subscriptions with different types of payment collection methods![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
You can collect payment for the migrated subscriptions either automatically with the default saved payment method or by sending an invoice that the customer can pay by the due date.
Example 1 (Basic): Migrate a yearly 500 USD subscription with a quantity of 1, starting on 1 January 2024, to be charged automatically using the default payment method.
ATTRIBUTE | customer (required) | start_date (required) | price (required) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
FIELD | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | none | charge_automatically |
Example 2 (Basic): Migrate a yearly 500 USD subscription with a quantity of 1, starting on 1 January 2024. This subscription is billed using an invoice sent to the customer, with a 30-day due date.
ATTRIBUTE | customer (required) | start_date (required) | price (required) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
FIELD | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | none | send_invoice | 30 |
Migrate subscriptions at different stages of subscription cycle![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Example 1 (Basic): Migrate a subscription that’s due for renewal. For example, migrate a 100 USD monthly subscription with a renewal date of 1 January 2024. The subscription renews on the 1st of every month.
- Set the
start_
to the current renewal date, so the subscription is charged immediately.date - Set the
billing_
to the next renewal cycle date.cycle_ anchor - Set
proration_
tobehavior none
.
ATTRIBUTE | customer (required) | start_date (required) | price (required) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
FIELD | cus_xxxx1 | 1704067200 | price_xxx1 | subscription_1 | 1706745600 | none | charge_automatically |
Example 2 (Basic): Migrate a paid subscription that’s in the middle of a billing cycle. For example, migrate a 100 USD monthly subscription with an original start date of 25 December. The migration date is 1 January, and the subscription renews on the 25th of every month.
- Set
backdate_
to the original start date of the subscription.start_ date - Set
billing_
to the upcoming renewal date.cycle_ anchor - Set
start_
to the migration date.date - Set
proration_
tobehavior none
to avoid charging the customer again and keep the subscription in a scheduled state until the next billing cycle.
ATTRIBUTE | customer (required) | start_date (required) | price (required) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
FIELD | cus_xxxx1 | 1704067200 | price_xxx1 | subscription_1 | 1706140800 | none | charge_automatically | 1703462400 |
Example 3 (Basic): Migrate subscriptions with trials. For example, migrate a basic 100 USD monthly subscription starting on 1 January 2024. The subscription is under a trial until 31 January 2024. After the trial ends, the subscription is charged automatically using the default payment method.
ATTRIBUTE | customer (required) | start_date (required) | price (required) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
FIELD | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | 1706659200 | none | charge_automatically | 1703462400 |
Example 4 (Basic): Migrate past-due subscriptions. For example, migrate a 100 USD monthly subscription with a last cycle start date of 25 December, which hasn’t been paid. Migrate this mid-cycle starting 1 January, with a renewal date on the 25th of each month. This creates a prorated invoice from 1 January to 25 January that Stripe can attempt to collect payment for.
To migrate subscriptions that are in an active cycle but haven’t been paid in the previous system, set proration_
to create_
to immediately create an invoice and collect payment. This also enters the subscription into Stripe’s dunning flow, if the payment is still unpaid.
ATTRIBUTE | customer (required) | start_date (required) | price (required) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
FIELD | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | 1706140800 | create_prorations | charge_automatically | 1703462400 |
Example 5: Migrate subscriptions that need to be cancelled at the end of the cycle. After migration, you can choose whether to charge these subscriptions, based on the migration timing (mid-cycle or at renewal).
They’re cancelled at the end of that period. For example, migrate a basic 100 USD monthly subscription starting on 1 January 2024. This subscription is automatically cancelled on 31 January 2024.
ATTRIBUTE | customer (required) | start_date (required) | price (required) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
FIELD | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | 1706140800 | none | charge_automatically | 1703462400 | TRUE |
Migrate subscriptions with taxes![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Example 1 (Basic): Migrate subscriptions to automatically calculate tax by enabling Stripe Tax. For example, migrate a 100 USD monthly subscription starting 1 January 2024, with Stripe Tax enabled to calculate the tax automatically.
The migration toolkit validates if you enabled Stripe Tax in advance, and if customers provided the required fields to calculate tax automatically. Make sure your customers provide the necessary information before migration.
ATTRIBUTE | customer (required) | start_date (required) | price (required) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
FIELD | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | TRUE | none | charge_automatically |
Example 2 (Basic): Migrate subscriptions and calculate tax using manual tax rates. For example, to migrate a basic $100 monthly subscription starting on 1 January 2024, with 10% tax created using manual tax rates:
- Create a 10% manual tax rate in the Dashboard (Product catalogue > Coupons).
- Use the tax rate ID in the migration CSV template.
ATTRIBUTE | customer (required) | start_date (required) | price (required) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
FIELD | cus_xxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | FALSE | 1706140800 | none | charge_automatically | txr_xxx1 |
Example 3 (Basic): If you use an external tax provider, such as Avalara or Vertex:
For migrated subscriptions where tax is already calculated, leave both automatic_
and default_
blank in the CSV.
After the subscriptions are migrated and live, they automatically follow the tax integration workflows you set up for new subscriptions in your Billing integration.
Migrate subscriptions with discounts![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Currently, the migration toolkit supports only one coupon per subscription.
Example 1 (Basic): You can migrate subscriptions with discounts that are applied after migration. For example, to migrate a $100 monthly subscription starting on 1 January 2024, with a 10% forever discount:
- Create a 10% coupon in the Dashboard (Product catalogue > Coupons).
- Use the coupon name in the migration CSV file.
ATTRIBUTE | customer (required) | start_date (required) | price (required) | quantity | metadata.third_party_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end | add_invoice_items.0.amount | add_invoice_items.0.product | add_invoice_items.0.currency |
FIELD | cus_xxxx1 | 1704067200 | price_xxx1 | 1 | subscription_1 | sample_coupon | none | charge_automatically |
Migrate subscriptions within Stripe accounts![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
The steps to migrate subscriptions from one Stripe account to another are the same as when migrating from a third-party system. Use the Billing migration toolkit to migrate subscriptions. You’ll need to export the subscription data for your CSV file from your old Stripe account.
Example 1 (Basic): To create a migration CSV for a Stripe-to-Stripe migration:
- Export the subscriptions from the old Stripe account using the Dashboard.
- Use the following CSV example as a reference to map fields between the old and new Stripe accounts.
ATTRIBUTE | customer (required) | start_date (required) | price (required) | quantity | metadata.old_Stripe_sub_id | automatic_tax | billing_cycle_anchor | coupon | trial_end | proration_behavior | collection_method | default_tax_rate | backdate_start_date | days_until_due | cancel_at_period_end |
FIELD | Export field: Customer ID (from previous account export) | Export field: Current Period End UTC (from previous account export) | Respective price ID in the new account | Export field: Quantity (from previous account export) | Export field: id (from previous account export) | TRUE if using Stripe tax in new account, else FALSE | Future billing date in new account | Respective coupon in the new account, if any | Respective trial in the new account, if any | create_ in case of prorated invoice, else none | charge_ or send_ | Respective tax rate in the new account, if any | Export field: Start Date UTC (from previous account export) | Specify if using send_ as collection method | Specify if a subscription is due to be cancelled at period end |
Migrate subscriptions with multiple phases![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
The migration toolkit doesn’t support adding multiple phases directly to a subscription. We recommend the following approach:
- Use the migration toolkit to migrate the initial phase of the subscription.
- After the migration, add the additional phases to the migrated subscription schedules. To do so, call the update endpoint or use the Stripe Subscriptions Dashboard.
- Adjust the
start_
of the migration to allow enough time between the scheduled and live status changes. This allows you to make the phase updates before the subscriptions go live.date
Full CSV specification![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Attribute | Type | Description |
---|---|---|
customer (required) | Stripe Customer ID | The identifier of the customer to create the subscription for. |
start_ (required) | Timestamp in epoch UNIX format | Determines when to create the subscription. You must provide a value that’s 24 hours (or greater) into the future. In test mode, you can set this to 1 hour in the future. |
price (required) | Stripe Price ID | Must be a recurring price. If migrating multiple items, use items. format instead. Ad-hoc prices are also supported with adhoc_ . |
quantity | Number | Determines quantity of a subscription. By default, each subscription is for one product, but Stripe allows you to subscribe a customer to multiple quantities of an item. |
items. (required) | Stripe Price ID | The ID of the price object. Must be a recurring price. |
items. | Number | Determines quantity of a subscription. By default, each subscription is for one product, but Stripe allows you to subscribe a customer to multiple quantities of an item. |
adhoc_ (required) | Integer | A positive integer in cents (or 0 for a free price). For more information, see Create a subscription. |
adhoc_ (required) | Stripe Product ID | The identifier of the product that belongs with the ad-hoc price. |
adhoc_ (required) | day , week , month or year | The billing frequency. |
adhoc_ (required) | String | A three-letter ISO currency code, in lowercase, for a supported currency. |
adhoc_ | Number | Determines quantity of a subscription. By default, each subscription is for one product, but Stripe allows you to subscribe a customer to multiple quantities of an item. |
metadata_ | String | If you’re doing a Stripe-to-Stripe migration, enter internal:Stripe . |
metadata_ | String | Attach these key-value pairs to an object. This is useful for storing additional information about the object in a structured format. |
automatic_ | Boolean | Specify true to use automatic tax settings by Stripe Tax. |
coupon | Stripe Coupon ID | The identifier of the coupon to apply to this subscription. |
trial_ | Timestamp | Sets the phase to trial from the start date to the trial_ date. You must specify a value that’s before the cycle/phase end date, and you can’t combine it with the trial. |
proration_ | create_ or none | Determines if the subscription creates prorations after migration. The default value is create_ . |
collection_ | charge_ or send_ | When charging automatically, Stripe attempts to pay the underlying subscription at the end of each billing cycle using the default source attached to the customer. The default value is charge_ . When sending an invoice, Stripe emails your customer an invoice with payment instructions, and marks the subscription as active. If using send_ , you must set days_ . |
default_ | Stripe Tax ID | Sets the subscription’s default_ . This also determines the invoice’s default_ for any invoices issued by the subscription during this phase. This value is incompatible with automatic_ . |
backdate_ | Timestamp in epoch UNIX format | Determines the start_ of the created subscription, which must occur in the past. If set, you must specify none for the proration_ . Doing so prevents the creation of a pro-rata invoice for the time between backdate_ and actual start_ . For more details, see backdating no charge. |
billing_ | Timestamp | Determines the future dates of when to bill the subscription to the customer. |
days_ | Integer | The number of days from when the invoice is created until it’s due. This is required and valid only for invoices with collection_ set to send_ . |
cancel_ | Boolean | Specify true to cancel a subscription at the end of the period. |