Products and Prices

Products and Prices define what you sell and how much it costs. They are catalog objects used by Checkout, invoices, and subscriptions.

Understanding Products and Prices early makes subscription integrations easier because subscriptions bill customers through recurring Prices.

Product versus Price

Resource	What it represents	Example
Product	The thing being sold or provisioned.	`Pro plan`, `API credits`, `T-shirt`, `EV charging membership`
Price	The amount, currency, and optional billing cycle for a Product.	`EUR 19.00/month`, `USD 199.00/year`, `EUR 9.99 one time`

A Product can have multiple Prices. This lets you keep provisioning logic stable while changing payment terms.

For example, one Pro plan Product can have:

a monthly recurring Price;
a yearly recurring Price;
a one-time setup fee Price;
different Prices for different currencies.

One-time and recurring Prices

Prices can be one-time or recurring.

Price type	Use when
`one_time`	The customer pays once, such as a physical good, setup fee, ticket, or one-off service.
`recurring`	The customer is billed on a schedule, such as monthly or yearly subscriptions.

Recurring Prices define the billing interval and usage model. This is why Products and Prices matter before building subscriptions: a Subscription item usually references a recurring Price.

Catalog-backed pricing versus inline pricing

Some APIs let you pass either a catalog Price or inline price_data.

Approach	Use when
Catalog Price	The same product or plan is sold repeatedly, shown in the dashboard, or reused by subscriptions.
Inline pricing	The amount is generated dynamically for a one-off flow.

For subscriptions, prefer catalog Prices when possible. Catalog Prices make plan management, dashboard review, invoice generation, and future subscription changes easier to reason about.

How Products and Prices connect to other APIs

flowchart LR
  Product["Product"]
  Price["Price"]
  Checkout["Checkout Session"]
  Subscription["Subscription"]
  Invoice["Invoice"]

  Product --> Price
  Price --> Checkout
  Price --> Subscription
  Subscription --> Invoice

Checkout can use Price-backed line items for customer-facing payments. Subscriptions use recurring Prices to determine how much to charge and how often. Invoices can include price and product snapshots so billing records remain understandable even if the catalog changes later.

Design guidance

Create separate Products for different goods, services, or entitlement models.
Create separate Prices for different currencies, billing intervals, or billing amounts.
Do not edit a Price to mean a different commercial offer after customers have used it. Create a new Price instead.
Use active=false when a Product or Price should no longer be used for new purchases.
Use metadata for stable internal references that do not belong in customer-facing names or descriptions.

Subscription readiness

Before creating subscriptions, make sure you understand:

which Product represents the service or plan;
which recurring Price represents the billing terms;
whether the Price is licensed or metered;
which customer and default payment method should be charged;
how invoice and renewal events will be handled through webhooks.

The subscription guide builds on these concepts.

API reference

Payment records

Accept Payments