Stripe Checkout and Prices API

Why should I update my Checkout integration to the new Prices API?

While you are not required to update your integration, we recommend that you upgrade to use the Prices API with Checkout so that you can take advantage of the following:

Integration Product type Old New
client-only one-time SKU Price
client-only recurring Plan Price
server one-time dynamic line item Price, dynamic Price
server recurring Plan Price, dynamic Price

Check out our migration guide for details on how to update your integration.

Do I have to update my Checkout integration to use the Prices API?

No, everything is backwards compatible. You can continue to use your old integration, and use Prices in place of Plans in the old integration flows.

Can I define a one-time item when I create a Checkout Session like I could prior to the Prices API?

Currently, no. You must first at least create a Product, then create a Price on top of it or use price_data on Checkout Session creation. You can continue to use the old integration if you prefer, but you cannot combine the ad-hoc line items with Prices.

How do I use mode if I have one time and recurring items?

Use mode=subscription if you are creating a Checkout Session with both recurring and one-time items. Use mode=payment if there are only one-time items.

Can I use both Prices and Plans at the same time with Checkout?

Yes. The following combinations are possible:

Integration type API type Objects Allow input? Output Behavior
Client-only Old (items) Plans and/or SKUs image.png return both line_items and display_items
Client-only Old (items) includes Prices image.png throw invalid request error linking to migration docs
Client-only New (lineItems) Plans, SKUs, and/or Prices ​​image.png
return line_items
Server Old (subscription_data[items] and line_items) Plans and/or custom line item ​​image.png
return both line_items and display_items
Server Old (subscription_data[items] and line_items) includes Prices ​​image.png
throw invalid request error linking to migration docs
Server New (line_items) includes Prices with one-time custom line items ​​image.png
throw invalid request error
use price_data for dynamic items (recurring or one-time) instead
Server New (line_items) Plans and/or Prices ​​image.png
return only line_items