Billing
Migrating to Prices

Migrating to Prices

Learn how to update your integration to use prices for one-time purchases and recurring billing.

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.

1 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:

2 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

3 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 should create a product and a price, and then pass the price in /v1/invoiceitems calls instead.


Before
After
curl https://api.stripe.com/v1/invoiceitems \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d unit_amount=2000 \ -d currency=usd \ -d quantity=1 \ -d description="Dashboard setup"
curl https://api.stripe.com/v1/products \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d name="Dashboard setup" curl https://api.stripe.com/v1/prices \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d product=prod_GQCD1WvlF5f0Ev \ -d unit_amount=2000 \ -d currency=usd curl https://api.stripe.com/v1/invoiceitems \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d price=price_def \ -d quantity=1

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:


Before
After
curl https://api.stripe.com/v1/subscriptions \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d "items[0][plan]"=plan_abc
curl https://api.stripe.com/v1/subscriptions \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d "items[0][price]"=plan_abc

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:


Before
After
curl https://api.stripe.com/v1/invoiceitems \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d unit_amount=2000 \ -d currency=usd \ -d quantity=1 \ -d description="Dashboard setup" curl https://api.stripe.com/v1/subscriptions \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d "items[0][plan]"=plan_abc
curl https://api.stripe.com/v1/subscriptions \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d "items[0][plan]"=plan_abc \ -d "add_invoice_items[0][price]"=price_def

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.


Before
After
curl https://api.stripe.com/v1/invoiceitems \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d unit_amount=2000 \ -d currency=usd \ -d quantity=1 \ -d description="Dashboard setup" curl https://api.stripe.com/v1/subscription_schedules \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d start_date=1598918400 \ -d phases[0][plans][0][plan]=plan_abc
curl https://api.stripe.com/v1/subscription_schedules \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d start_date=1598918400 \ -d phases[0][plans][0][price]=plan_abc \ -d phases[0][add_invoice_items][0][price]=price_def

Checkout

Please refer to the Checkout prices migration guide for more details on how to migrate.

Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.