Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
How subscriptions work
How to model subscriptions
Get started
Quickstart
Design an integration
Build a subscriptions integration
Integrate the customer portal
Migrate subscriptions to Stripe
Billing resources
Coupons
Customers
Subscriptions
Subscription invoices
Manage subscriptions
Change subscriptions
Usage-based billing
Use trial periods
Set payment methods
Subscriptions with multiple products
Set subscription quantities
Subscription webhooks
Schedule subscriptions
Tax
Integrate with Salesforce
Manage recurring revenue
Revenue recognition
Revenue recovery
Subscription metrics
Testing
Test your integration
Test clocks
Metered billing with Elements
Fixed-price billing with Elements
Per-seat billing with Elements
Migrate to Prices
Strong Customer Authentication (SCA)
Invoices API updates
Improved tax support
Testing
No-code options
Billing
·
HomePaymentsSubscriptions

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.

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 an invoice API.
  • Bill customers with subscriptions.
  • Use subscription schedules to manage subscriptions for your customers.
  • Use Checkout with custom line_items, items with SKUs, or subscription_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 we’ve renamed a few fields and some are now optional. The following table contains a summary of the changes to the API for creating prices:

PlanPrice
amount optionalunit_amount optional
amount_decimal optionalunit_amount_decimal optional
interval requiredrecurring[interval] optional
interval_count required, defaults to 1recurring[interval_count] optional
usage_type optionalrecurring[usage_type] optional
aggregate_usage optionalrecurring[aggregate_usage] optional
transform_usage optionaltransform_quantity optional

To configure subscription trials, use the Subscriptions API:

  • trial_end—Indicates the trial’s end date.
  • trial_period_days—Indicates the number of trial period days.

You can also inherit the trial from a plan by using the trial_from_plan parameter.

Update your integration to use prices

See the instructions for each product and feature that you use:

  • Invoices
  • Subscriptions
  • Subscription schedules
  • Checkout

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.

Before
After
Terminal
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"
Terminal
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
Terminal
curl https://api.stripe.com/v1/subscriptions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d "items[0][plan]"=plan_abc
Terminal
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
Terminal
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"
Terminal
curl https://api.stripe.com/v1/subscriptions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d "items[0][plan]"=plan_abc
Terminal
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
Terminal
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"
Terminal
curl https://api.stripe.com/v1/subscription_schedules \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d start_date=1659365484 \ -d phases[0][plans][0][plan]=plan_abc
Terminal
curl https://api.stripe.com/v1/subscription_schedules \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d customer=cus_GWZ4fLmuDlz4Ye \ -d start_date=1659365484 \ -d phases[0][plans][0][price]=plan_abc \ -d phases[0][add_invoice_items][0][price]=price_def

Checkout

For more information on how to migrate, see the Checkout prices migration guide.

Was this page helpful?
Questions? Contact us.
View developer tutorials on YouTube.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Identify how you use plans, products, and payment flows
Review the differences between plan and price
Update your integration to use prices
Stripe Shell
Test mode
▗▄ ▄▟█ █▀▀ ▗▟████▙▖ ██████ ███▗▟█ ███ ███▗▟██▙▖ ▗▟█████▙▖ ███▖ ▀▀ ███ ███▀▀▀ ███ ███▀ ███ ███ ███ ▝▜████▙▖ ███ ███ ███ ███ ███ █████████ ▄▄ ▝███ ███ ▄ ███ ███ ███▄ ███ ███ ▄▄ ▝▜████▛▘ ▝▜███▛ ███ ███ ███▝▜██▛▘ ▝▜█████▛▘ ███ ▀▘
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to Stripe docs and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$