Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Billing
OverviewAbout the Billing APIs
Subscriptions
    How subscriptions work
    Quickstart
    Use cases
    Build your integration
    Subscription features
      Subscription invoices
      Subscription schedules
      Subscription pricing
      Recurring pricing models
      Embed a pricing table
      Start subscriptions
      Set quantities
      Set billing cycles
      Backdate subscriptions
      Subscribe to multiple items
      Set trial periods
      Apply coupons
      Migrate subscriptions to Stripe
        Migrate subscriptions using a toolkit
        Migrate subscriptions using Stripe APIs
      How credit prorations are calculated
      Subscription payments
      Subscription payment methods
      Integrate with third-party payment processing
      Collection methods
      Strong Customer Authentication (SCA)
      Manage subscriptions
      Modify subscriptions
      Manage pending updates
    Entitlements
    Analytics
Invoicing
Usage-based billing
Quotes
Customer management
Billing with other products
Revenue recovery
Automations
Revenue recognition
Test your integration
Tax
Overview
Use Stripe tax
Manage compliance
Reporting
Overview
Select a report
Configure reports
Reports API
Reports for multiple accounts
Revenue recognition
Data
OverviewSchema
Custom reports
Data Pipeline
Data management
HomeRevenueSubscriptionsSubscription featuresMigrate subscriptions to Stripe

Migrate subscriptions to Stripe Billing using Stripe APIs

Learn how to migrate your existing subscriptions to Stripe using Stripe APIs.

Learn how to migrate your existing subscriptions from a third-party, an in-house system, or an existing Stripe account to Stripe Billing using Stripe APIs.

Before you begin

  1. If you haven’t already, review the migration stages.
  2. Set up a Stripe Billing integration. This prerequisite is only required once before importing subscriptions to Stripe, and you don’t need to repeat it for future migrations.
  3. Request a PAN data import from your current processor. If you’re attempting a Stripe-to-Stripe migration, this prerequisite isn’t necessary because you’re already using Stripe for payment processing.

Manage legacy products and prices

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:

Command Line
cURL
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.

Command Line
cURL
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

Import your subscriptions

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 of 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.

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 with 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, which might 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.

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 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 at 12:00 AM UTC.

Command Line
cURL
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

Confirm your migration

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 of the Subscriptions in Stripe. You can pass the created parameter to filter for recently created Subscriptions.

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

See also

  • Subscriptions schedules
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc