Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Overview
Online payments
Products and prices
Invoicing
Subscriptions
    Overview
    How subscriptions work
    Recurring pricing models
    Get started
    Quickstart
    Integrate a SaaS business
    Embed a pricing table
    Design an integration
    Build a subscriptions integration
    Migrate subscriptions to Stripe
    Billing resources
    Coupons
    Customers
    Subscriptions
    Subscription invoices
    Manage subscriptions
    Change subscriptions
    Usage-based billing
    Use trial periods
    Set payment methods
    Subscriptions with multiple products
    Set subscription quantities
    Subscription webhooks
    Schedule subscriptions
    Tax
    Sales-led B2B billing
    Integrate with Salesforce
    Manage recurring revenue
    Revenue recognition
    Revenue recovery
    Subscription metrics
    Customer management
    Overview
    Set up the the no-code customer portal
    Set up the customer portal with the API
    Configure the customer portal
    Testing
    Test your integration
    Test clocks
    Strong Customer Authentication (SCA)
    Invoices API updates
Quotes
In-person payments
Multiparty payments
After the payment
Add payment methods
Payment Links
Stripe Checkout
Stripe Elements
About the APIs
Regulation support
Implementation guides
Testing
Billing
·
HomePaymentsSubscriptions

Migrate subscriptions to Stripe Billing

Import subscriptions from other sources into Stripe.

If you have subscriptions from other sources, like an internal system or a third-party billing solution, you can import them into Stripe Billing with Stripe APIs.

Here are the high-level steps:

  1. Import customers with payments data.
  2. (Conditionally) Import customers without payments data.
  3. Create a pricing model.
  4. Import subscriptions.
  5. Confirm your migration.

Before you start, make sure you know:

  • Your current payment processor.
  • Your current subscription provider.
  • Your pricing model.
  • How you want to charge your customers on a recurring basis.

Do you have questions about migration?

Enter your email address and we'll contact you shortly.
Read our privacy policy.
Signed up successfully!
Thank you! We'll be in touch soon.

Import customers with payments data into Stripe

You need to import your payments data before you begin migrating subscriptions to Stripe. For complete details, read the payments migration guide.

If you expect that you’ll have overlap between fully moving off of your old payment processor and moving to Stripe, set up your Stripe integration to collect customer payment information to charge any new customers. Learn more about preparing your integration.

Make sure that you can handle updates to payment information during the migration process.

Import customers without payments data into Stripe
Conditional

The payments data import in the previous step also imports customer records. You only need to complete this step if:

  • You store the customer data in a different system than your payments data.
  • The customers don’t have associated payment methods. This might include customers subscribed through a free trial or freemium models.

Otherwise, you can skip this step and create a pricing model.

Test mode

Use test mode to run through the customer import at least once before running the import in live mode. You need to remap your script:

  • If you wipe the data in test mode and rerun the import.
  • When you move to live mode, because the customer IDs are different in test mode and live mode.

Map customer data

Before you start, decide how to map data from your source system to Stripe’s customer resource, using the metadata field to store arbitrary data. Map all the customer data you have, including any unique third-party IDs, VAT numbers, tax IDs, and tax codes.

Important fields for migrating customers

The following table describes the most important fields to consider when importing subscriptions.

FieldDescription
Third-party metadataImport any additional data fields from your source data. These can include product names, plan names, and third-party application IDs.
Tax settingsInclude any tax IDs, VAT IDs, or other tax information.

Stripe Tax

If you’re using Stripe Tax, you must include full shipping and billing addresses for each customer, otherwise Stripe Tax can’t automatically calculate tax. For details, read about the supported address formats that Stripe Tax uses. After you create the customers in Stripe, you can use the Dashboard or Customers API to confirm the customer’s tax location status.

Create customers

When you’re ready to perform the import, create an array of your existing customers, then use the list to create a customer in Stripe for each existing customer. If you have a large number of customers, you might want to use a script for this process. Here’s an example of how to create one customer with mapped data.

For Stripe Tax to automatically calculate tax obligations, you need to provide an address for software purchases and a shipping_address for physical goods. Read the docs to learn more about:

  • How Stripe Tax validates customer locations.
  • How to handle location validation in your subscriptions integration.
Command Line
curl https://api.stripe.com/v1/customers \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d email="{{CUSTOMER_EMAIL}}" \ -d name="{{CUSTOMER_NAME}}" \ -d description="Imported customer from source system" \ -d "metadata[tax_id]"="{{CUSTOMER_TAX_ID}}" \ -d "metadata[OLD_CUSTOMER_ID]"="{{THIRD_PARTY_ID}}" \ -d "shipping[address][city]"=Brothers \ -d "shipping[address][country]"=US \ -d "shipping[address][line1]"="27 Fredrick Ave" \ -d "shipping[address][postal_code]"=97712 \ -d "shipping[address][state]"=CA \ -d "shipping[name]"="{{CUSTOMER_NAME}}" \ -d "address[city]"=Brothers \ -d "address[country]"=US \ -d "address[line1]"="27 Fredrick Ave" \ -d "address[postal_code]"=97712 \ -d "address[state]"=CA

Create your pricing model on Stripe

Subscriptions in Stripe require a customer and at least one recurring Price. Before you import your subscriptions, you need to create a pricing model that reflects your business by creating Product and Price objects through the Dashboard or API.

The following example uses a good-better-best pricing model with yearly and monthly prices. Read the guides to learn more about all pricing models and how to get started with Products and Prices.

You can type product.new into the address bar of any browser to jump straight to the Product Editor.

To create a good-better-best model on Stripe through the Dashboard follow the steps below.

First, create the Basic product. To learn about all the options for creating a product, see the prices guide.

  1. Go to the Products tab.
  2. Click +Add product.
  3. Enter the Name of your product.
  4. (Optional) Add a Description. The description appears at checkout, on the customer portal, and in quotes.

Next, create the monthly price for the Basic product:

  1. Select Standard pricing for the Pricing model, then select Recurring.
  2. Enter the price amount-in this case, 10.00.
  3. Select Monthly for the Billing period.

Then, create the yearly price for the Basic product:

  1. Click + Add another price.
  2. Select Standard pricing for the Pricing model, then select Recurring.
  3. Enter the price amount-in this case, 100.00.
  4. Select Yearly for the Billing period.
  5. Click Save product to save the product and price. You can edit the product and price later.

Legacy products and prices

If you have legacy pricing models that you need to continue supporting in Stripe, we recommend creating a placeholder product, like Legacy plan. Here’s an example:

Command Line
curl https://api.stripe.com/v1/products \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d id="{{NEW_PRODUCT_ID}}" \ -d name="Legacy plan" \ -d description="Imported legacy plan from source system" \ -d "metadata[OLD_PRODUCT_ID]"="{{OLD_PRODUCT_ID}}"

When you need to update subscriptions with legacy plans, pass in the prices as needed using items.price_data. This overrides any existing legacy price. To learn more, read variable pricing.

Command Line
curl https://api.stripe.com/v1/subscriptions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d customer="{{CUSTOMER_ID}}" \ -d "items[0][price_data][currency]"=USD \ -d "items[0][price_data][product]"="{{PRODUCT_ID}}" \ -d "items[0][price_data][recurring][interval]"=month \ -d "items[0][price_data][recurring][interval_count]"=3 \ -d "items[0][price_data][unit_amount]"=1000 \ -d "items[0][quantity]"=1

Import your subscriptions

After you’ve imported your customers and created a pricing model, you’re ready to start importing your subscriptions. You should be able to export subscription data from third-party systems through their UI or API. Contact your subscriptions processor if they don’t provide this option through either interface.

To import subscriptions, use your list of customers to create the appropriate subscription for each one. For example, if Jenny Rosen is subscribed to a monthly Basic plan in your old model, use the monthly recurring price associated with that level when you create their subscription in Stripe.

Make source data Stripe-compatible

Before you start importing subscriptions into Stripe, make sure that all of your source data is compatible with Stripe’s expected format.

Important fields for migrating subscriptions

As you did when importing customers, map all the relevant subscription fields from your data source to the metadata field of the subscriptions you create in Stripe. The following table describes other important fields to consider when importing subscriptions.

FieldDescription
customerMake sure that you’ve properly mapped the customer ID from your source data to the new customer ID in Stripe.
phases.items.priceMake sure that you’ve mapped the price ID from your source data to the new price ID in Stripe.
current_phase.start_dateMake sure that the subscription schedule you define in Stripe lines up and maintains continuity from your original source data. For example, if a customer has 6 months left on a yearly subscription in your source system, make sure that billing_cycle_anchor and start_date reflect the correct mid-cycle term.
Third-party metadataImport any additional data fields from your source data. These may include product names, plan names, and third-party application IDs.
Tax settingsInclude any tax IDs, VAT IDs, or other tax information.

Prepare legacy prices

If you created placeholders for legacy prices, you need to map those prices to the subscriptions and customers you’re importing. For each subscription with a legacy price, use the price_data parameter of the Subscriptions API to pass in information about the price and subscription. The required fields are:

ParameterDescription
currencyCurrency of the price, in three-letter ISO format.
productID of the placeholder product. You can use this for all of the legacy prices.
recurringInformation about the amount and frequency of the recurring price.
recurring.intervalFrequency of the interval-day, week, month, or year.
recurring.interval_countNumber of intervals between billings. For example, setting interval=day and interval_count=30 means that you bill the customer every 30 days. The maximum interval is 1 year (1 year, 12 months, or 52 weeks).
recurring.unit_amount_decimalSame as unit_amount, but allows you to specify more granular decimal amounts in cents, up to 12 decimals. You can only set one of unit_amount and unit_amount_decimal.

Import subscription data into Stripe

After you’ve prepared your source data, you can start importing subscriptions into Stripe.

Test mode

Use test mode to run through the pricing model import at least once before running the import in live mode. You need to remap your script:

  • If you wipe the data in test mode and rerun the import.
  • When you move to live mode, because the price IDs are different in test mode and live mode.

In test mode, you can use test clocks to simulate subscriptions advancing through time. This allows you to see how the migrated subscriptions work in production.

Create subscriptions

While you can use the Subscription API to create subscriptions, we recommend using the Subscription Schedules API. With this API, you can schedule subscriptions to start in the future. For example, it’s the only way to start monthly subscriptions more than 30 days in advance. The ability to start subscriptions in the future also allows you to review the import before you start to bill your customers in production.

Additionally, the Schedules API provides phases, which provide much more flexibility in defining settings like tax behavior, collection method, and coupon usage within more granular intervals. You can also define different behavior for different intervals. For example, you could apply a coupon only for the first 3 months of a yearly subscription.

Here’s how to create subscriptions that start on June 1, 2022, 12:00 AM UTC.

Command Line
curl https://api.stripe.com/v1/subscription_schedules \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d customer=
{{CUSTOMER_ID}}
\ -d "default_settings[billing_cycle_anchor]"=phase_start \ -d "phases[0][items][0][price]"=
{{PRICE_ID}}
\ -d start_date=1654066801

Confirm your migration

After you’ve imported your subscriptions, use the Dashboard or API to confirm that the subscriptions exist in Stripe.

In the Dashboard, go to Billing > Subscriptions and look for your imported subscriptions. Use filters such as created date to find your subscriptions. If you scheduled the subscriptions to start at a later date, look at the Scheduled tab.

Make sure that the test mode toggle matches the mode you used to import the subscriptions. If you imported using test mode and view the subscriptions in live mode, you won’t see the imported subscriptions.

See also

  • Test your integration
Was this page helpful?
Need help? Contact Support.
Watch our developer tutorials.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Import customers with payments data into Stripe
Import customers without payments data into Stripe
Create your pricing model on Stripe
Import your subscriptions
Confirm your migration
See also
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to your Stripe account and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$