Checkout prices migration guide
Learn how to update your integration to use prices with Stripe Checkout.
The Prices API integration includes:
- Unified modeling for Checkout items—instead of plans, SKUs , and inline line items, every item is a price .
- The ability to render product images for recurring items.
- The ability to create a reusable product and price catalog and as opposed to one-time line items.
- The ability to create inline pricing for subscriptions .
- Dynamic tax rates for subscriptions and one-time payments .
If you don’t want to migrate, you can continue to use your current integration, but we won’t add new features. You can use any new plans or recurring prices you create in the plan parameter of your existing API calls.
Products and prices overview
Prices are a core entity within Stripe that work with subscriptions, invoices, and Checkout. Each price is tied to a single Product, and each product can have multiple prices. Different physical goods or levels of service are represented by products.
Prices define the base price, currency, and—for recurring products—the billing cycle. This allows you to change and add prices without needing to change the details of what you offer. For example, you might have a single “gold” product that has prices for 10 USD per month, 100 USD per year, 9 EUR per month, and 90 EUR per year. Or you might have a blue t-shirt with 20 USD and 15 EUR prices.
One-time payments
Integrations for one-time payments have the following changes:
- Instead of ad-hoc line items (that is, setting the name, amount, and currency), creating a Checkout Session requires creating a product and, usually, a price .
- mode is now required.
The client-side code remains the same.
Mapping table
Instead of defining each field on line_items, Checkout uses the underlying product and price objects to determine name, description, amount, currency, and images. You can create products and prices with the API or Dashboard.
| Without prices | With prices |
|---|---|
line_items.name | product.name |
line_items.description | product.description |
line_items.amount | price.unit_amount price_data.unit_amount (if defined when the Checkout Session is created) |
line_items.currency | price.currency price_data.currency (if defined when the Checkout Session is created) |
line_items.images | product.images (displays the first image supplied) |
Server-side code for inline items
Previously, you could only create one-time items inline. With prices, you can continue to configure your items inline, but you can also define your prices dynamically with price_data when you create the Checkout Session.
When you create the Checkout Session with price_data, reference an existing product ID with price_data.product, or define your product details dynamically using price_data.product_data. The following example demonstrates the flow for creating a one-time item.
Command Line
Select a language
curl
Ruby
Python
PHP
Node.js
Java
Go
.NET
No results
Server-side code for one-time prices
With this integration, you can create a product and price catalog upfront instead of needing to define the amount, currency, and name each time you create a Checkout Session.
You can either create a product and price with the Prices API or through the Dashboard. You’ll need the price ID to create the Checkout Session. The following example demonstrates how to create a product and price through API:
Command Line
Select a language
curl
Ruby
Python
PHP
Node.js
Java
Go
.NET
No results
Subscriptions
Integrations for recurring payments have the following changes:
- All items are passed into a single line_items field, instead of subscription _ data. items .
- mode is now required. Set mode=subscription if the session includes any recurring items.
The client-side code remains the same. Existing plans can be used wherever recurring prices are accepted.
Server-side code with plans
Here is a before and after example of creating a Checkout Session with a trial and using an existing plan, which can be used interchangeably with a price. The plan is now passed into line_items instead of subscription_data.items.
Command Line
Select a language
curl
Ruby
Python
PHP
Node.js
Java
Go
.NET
No results
Server-side code for recurring price with setup fee
If you have recurring plans with a one-time setup fee, create the product and price representing the one-time fee before creating the Checkout Session. See the mapping table for how the line_items fields map to this integration. You can either create a product and price through the Prices API or through the Stripe Dashboard. You can also create the one-time item inline. The following example uses an existing price ID:
Command Line
Select a language
curl
Ruby
Python
PHP
Node.js
Java
Go
.NET
No results
Response object changes
Instead of listing items with display_items, the Checkout Session object uses line_items. The line_items field doesn’t render by default as display_items did, but you can include it using expand when creating a Checkout Session:
Command Line
Select a language
curl
Stripe CLI
No results
Webhook changes
Since line_items is includable, the checkout.session.completed webhook response doesn’t list items by default. The smaller response object enables you to receive your Checkout webhooks faster. You can retrieve items with the line_items endpoint:
Command Line
Select a language
curl
Stripe CLI
No results
For more details, see fulfilling orders with Checkout.