Migrating to Prices
The Prices API adds more flexibility to how you charge customers. It also replaces the Plans API, so Stripe recommends migrating your existing integration to work with prices. To migrate, you need to identify how you use plans, products, and payment flows and then update these parts of your integration to use the Prices API.
Identify how you use plans, products, and payment flows
The Prices API impacts the Invoices, Subscriptions, and Checkout APIs. Stripe recommends updating your integration if you:
- Bill your customers using invoice items and the create invoice API.
- Bill customers with subscriptions.
- Use subscription schedules to manage subscriptions for your customers.
- Use Checkout with custom
line_items
,items
with SKUs, orsubscription_data[items]
with plan IDs. See the Checkout migration guide to make sure you’re using the latest version of Checkout before working through the rest of this guide.
Review the differences between plan and price
The price object is similar to the plan object, but a few fields have been renamed and some fields are now optional. Below is a summary of the changes to the API for creating prices:
Plan | Price |
---|---|
amount optional | unit_amount optional |
amount_decimal optional | unit_amount_decimal optional |
interval required | recurring[interval] optional |
interval_count required, defaults to 1 | recurring[interval_count] optional |
trial_period_days optional | recurring[trial_period_days] optional |
usage_type optional | recurring[usage_type] optional |
aggregate_usage optional | recurring[aggregate_usage] optional |
transform_usage optional | transform_quantity optional |
Update your integration to use prices
See the instructions for each product and feature that you use:
Invoices
If you manually create invoice items to bill your customers, replace unit_amount
or amount
with a price
and quantity
. For example, if you charge a 20 USD setup fee, you pass the unit_amount
and quantity
in every /v1/invoiceitems
call. Instead, you create a product and a price, and then pass the price in /v1/invoiceitems
calls instead.
curl https://api.stripe.com/v1/invoiceitems \ -u
: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d unit_amount=2000 \ -d currency=usd \ -d quantity=1 \ -d description="Dashboard setup"sk_test_4eC39HqLyjWDarjtT1zdp7dc
curl https://api.stripe.com/v1/products \ -u
: \ -d name="Dashboard setup" curl https://api.stripe.com/v1/prices \ -usk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d product=prod_GQCD1WvlF5f0Ev \ -d unit_amount=2000 \ -d currency=usd curl https://api.stripe.com/v1/invoiceitems \ -usk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d price=price_def \ -d quantity=1sk_test_4eC39HqLyjWDarjtT1zdp7dc
Subscriptions
If you use subscriptions to bill your customers, you can continue to pass plan IDs into the Prices API. Plans are recurring prices, and can be updated and retrieved in the /v1/prices
endpoints. You can also pass plan IDs into the various price
fields. For example, if you have a plan with ID plan_abc
:
curl https://api.stripe.com/v1/subscriptions \ -u
: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d "items[0][plan]"=plan_abcsk_test_4eC39HqLyjWDarjtT1zdp7dc
curl https://api.stripe.com/v1/subscriptions \ -u
: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d "items[0][price]"=plan_abcsk_test_4eC39HqLyjWDarjtT1zdp7dc
If you previously implemented one-time fees on subscriptions by adding invoice items to a customer or subscription, you may continue to do so. You can also pass a price and quantity in add_invoice_items
within the Subscriptions API. For example, if you previously included a setup fee when you created subscriptions, you had to create a pending invoice item and create the subscription. You can now do this in a single API call:
curl https://api.stripe.com/v1/invoiceitems \ -u
: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d unit_amount=2000 \ -d currency=usd \ -d quantity=1 \ -d description="Dashboard setup"sk_test_4eC39HqLyjWDarjtT1zdp7dc
curl https://api.stripe.com/v1/subscriptions \ -u
: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d "items[0][plan]"=plan_abcsk_test_4eC39HqLyjWDarjtT1zdp7dc
curl https://api.stripe.com/v1/subscriptions \ -u
: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d "items[0][plan]"=plan_abc \ -d "add_invoice_items[0][price]"=price_defsk_test_4eC39HqLyjWDarjtT1zdp7dc
This subscription appends a 20 USD invoice item for the setup fee defined in price_def
to the first invoice.
Subscription schedules
For subscription schedules, replace all references to plan
with price
, and pass add_invoice_items
into phase configurations, similar to the migration for subscriptions above.
curl https://api.stripe.com/v1/invoiceitems \ -u
: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d unit_amount=2000 \ -d currency=usd \ -d quantity=1 \ -d description="Dashboard setup"sk_test_4eC39HqLyjWDarjtT1zdp7dc
curl https://api.stripe.com/v1/subscription_schedules \ -u
: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d start_date= \ -d phases[0][plans][0][plan]=plan_abcsk_test_4eC39HqLyjWDarjtT1zdp7dc
curl https://api.stripe.com/v1/subscription_schedules \ -u
: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d start_date= \ -d phases[0][plans][0][price]=plan_abc \ -d phases[0][add_invoice_items][0][price]=price_defsk_test_4eC39HqLyjWDarjtT1zdp7dc
Checkout
Please refer to the Checkout prices migration guide for more details on how to migrate.