Migrate subscriptions to Stripe Billing

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.

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.

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.

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

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.

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:

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.

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

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.

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:

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.

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

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