Migrate subscriptions to Stripe Billing using toolkit
Learn how to migrate your existing subscriptions to Stripe using the toolkit.
Use the Billing migration toolkit to migrate your existing subscriptions from a third-party system, home-grown system, or an existing Stripe account to Stripe Billing.
Before you begin![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
- If you haven’t already, review the migration stages.
- Set up a Stripe Billing integration before you begin migration. This is a one-off setup that you don’t need to repeat for future migrations.
- Request a PAN data import from your current processor. This step is only required if you’re migrating to Stripe from another processor. If you’re migrating from Stripe to Stripe, you can skip this prerequisite.
- If you’re migrating from a third-party or home-grown system, carefully time the cancellation of your existing subscriptions and the creation of new ones in Stripe. To avoid missing a billing period, create the new subscriptions in Stripe first, before cancelling the old subscriptions. To avoid double billing, cancel subscriptions in your old system before the subscriptions are set to charge. For subscriptions with upcoming billing dates close to migration, schedule them to start after the cycle so the final bill is in the old system.
Open the Billing migration toolkit![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Select the test-mode toggle in the top right corner if you want to run a test migration first.
Navigate to Dashboard > Subscriptions > Migrations.
Alternatively, you can click the overflow menu () next to + Create subscription, and select Migrate subscriptions.
To start your migration, click Let’s get started.
Download a CSV file![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
First, export your existing subscriptions by matching the exported data to a migration-compatible CSV file. You can create your own CSV file, or download any of the following CSV templates provided by Stripe:
You can also find examples of CSV files for common migration use cases in the Toolkit CSV reference.
Click Download CSV template.
Choose a CSV template (basic, multi-price items, or ad-hoc pricing) based on your billing use case.
Basic CSV
This example shows a migration for common subscription use cases such as quantity, taxes, billing anchor, discounts, trials, and backdating.
Specify the following fields for a Basic CSV file:
Multi-price items CSV
This example shows a migration that has multiple products per subscription.
Specify the following fields for a Multi-price items CSV file:
Ad-hoc prices CSV
This example shows handling a subscription migration using ad-hoc pricing for existing products.
Specify the following fields for an Ad-hoc pricing CSV file:
In the CSV file, specify the details of the subscriptions you want to export.
For Stripe-to-Stripe migrations
If you’re migrating subscriptions within Stripe accounts, refer to the CSV example before you specify and upload a CSV file.
Upload a CSV file![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Click Upload CSV. The CSV file size limit is 120 MB.
Stripe validates the file to verify that the uploaded subscriptions are in the required CSV format. This process might take up to a few hours, depending on the size of the file. If the file is valid, you can proceed to the next step in the migration.
Resolve validation errors![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
If you have any errors in your uploaded file, the toolkit displays a failure summary. To resolve the errors:
Click Download file to review errors.
Review the
processing_
column to see the errors.error Correct all the errors. Common errors include:
Error Troubleshooting Invalid dates Make sure all the dates are in epoch or Unix timestamp format. Incorrect start_
rangedate Make sure the start_
for each subscription is at least 24 hours in the future.date Missing data Make sure every record contains the required fields. Incompatible price and tax Make sure prices for specified tax rates have the same tax_
(inclusive versus exclusive).behavior Click Upload revised file to re-upload the corrected CSV (the CSV file size limit is 120 MB).
Wait for re-validation to see the latest validation status.
Review uploaded subscriptions![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
After Stripe validates your CSV file, review the summary of your uploaded subscriptions for any discrepancies:
Cross-check the summary for the correct:
- Date of upload
- Uploaded file name
- Number of subscriptions
- Number of customers
- First subscription go-live date
If everything is valid, click Start migration.
If you see errors, click Cancel migration and restart the migration from Download a CSV file.
Track migration progress![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
After you review your uploaded subscriptions, track the progress of your migration:
Migration in progress![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Your subscriptions are queued to schedule on the specified start date. This process can take a few minutes to a few hours, depending on the size of the file. For example, the validation and migration for 100,000 subscriptions takes approximately 30 minutes to complete.
The Billing migration toolkit uses the Subscription schedule to migrate your subscriptions. This allows your subscriptions to remain in a scheduled state for 24 hours before going live. In test mode, the buffer time is reduced to 1 hour for faster evaluation and testing.
Scheduled subscriptions![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
After migration, your subscriptions remain in a scheduled state for 24 hours before going live. You have 10 hours to cancel these scheduled subscriptions using the toolkit.
Currently, you can’t update scheduled subscriptions using the toolkit. If you want to update your scheduled subscriptions, you can either call the update endpoint, or update each subscription (one-by-one) in the Subscriptions Dashboard.
Customers can’t cancel scheduled subscriptions from their customer portal. They can only cancel live subscriptions.
Go live with subscriptions![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
After 24 hours, your scheduled subscriptions go live and charge customers on their applicable start dates. You can view all your live subscriptions in the Subscriptions Dashboard.
After the migration goes live, we recommend you monitor your subscriptions starting from the first payment. Make sure the charge dates and amounts for the migrated subscriptions match the specified start_date.
Customers can cancel live subscriptions from their customer portal.
View all migrations![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To view all of your migrations:
Select the migration you want to review in Migrations.
To open a migration, click View in the dropdown menu.
You can track the following fields:
- Upload date
- File name
- Stripe billing migration id
- Number of subscriptions
- Migration status
OptionalCancel a migration![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
If you identify any problems with the scheduled subscriptions, you can roll back the migration and revert the scheduled subscriptions. The Dashboard displays a timestamp to indicate if you can still cancel the migration using the toolkit. You have 10 hours from when you scheduled the subscriptions to cancel them. After 10 hours, the cancel option is disabled in the toolkit.
- Find the migration you want to cancel in your Migrations.
- Click Cancel migration in the dropdown menu.
Cancel after 10 hours![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
To cancel the migration after 10 hours, you can either call the cancel endpoint, or individually cancel each subscription (one-by-one) in the Subscriptions Dashboard.
OptionalRun multiple migrations![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
You can run as many simultaneous subscription migrations as you want. For large migrations, divide the subscriptions into batches and start with a small batch. This can help you quickly identify any validation issues and save validation time.
To start a new migration:
Click Start new migration.
Restart the migration process from Download a CSV file.
You can also find examples of CSV files for common migration use cases in the Toolkit CSV reference.