Migrate subscriptions to Stripe Billing using Stripe APIs

If you have legacy pricing models that you need to continue supporting in Stripe, create a placeholder product, such as Legacy plan. Here’s an example:

curl https://api.stripe.com/v1/products \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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, see variable pricing.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 import your customers and create a pricing model, you can 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 a subscriber has a monthly Basic subscription 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 your source data is compatible with our expected format.

Important fields for migrating subscriptions

If you use relevant subscription data in your custom integration that Stripe doesn’t also use, you can apply your data 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.

Testing

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

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

In a sandbox, 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 Subscription Schedules API provides phases, which provide much more flexibility in defining settings such as tax behaviour, collection method, and coupon usage within more granular intervals. You can also define different behaviour 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 1 June 2022 at 00:00 UTC.

curl https://api.stripe.com/v1/subscription_schedules \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 API to confirm that the subscriptions exist in Stripe.

Use the list Subscriptions API to view all the Subscriptions in Stripe. You can pass the created parameter to filter for recently created Subscriptions.

curl -G https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "created[gt]"=1647294709