Products and Prices

Learn how to create and use products and prices.

Are you selling physical goods or managing a catalog of many products and prices? We’re working on some new features for the products and prices APIs. If interested, email us at product-catalog-beta@stripe.com and we’ll reach out when we have more information to share.

If you have existing Plans, you can continue to use them for recurring billing. You can keep using the Plans API or you can seamlessly switch to the Prices API and pass plan IDs in place of price IDs.

You can now model your business and product offerings in one place. Products define what you sell and Prices track how much and how often to charge. They can be used for recurring or one-time purchases and support various business structures from tiers to usage based billing. This is a core entity within Stripe that works with subscriptions, invoices, and Checkout.

Prices enable the following use cases:

A software provider who charges a one-time setup fee whenever a new subscription is created
An eCommerce store who sends a recurring box of goods for $10 / month and wants to allow customers to purchase one-time add-ons
A professional services firm that can now create a standard list of services and choose from that list per invoice instead of typing out each line item by hand
A non-profit organization who allows donors to define a custom recurring donation amount per customer

Create a product

Products are what you sell and you need to create at least one product before you can charge for it. This guide uses a SaaS analytics business as an example. If you only have a few products, you should create and manage them in the Dashboard but you can use the API too. If you set up your business model in the Dashboard in test mode, you can copy each of your products over to live mode using the Copy to live mode button in the product details page.

The basic product for this SaaS business is an analytics dashboard. You can use the examples below to create a product using the API or the Stripe CLI:

Terminal

curl https://api.stripe.com/v1/products \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "name"="Starter Dashboard"

When customers first sign up, they’re also charged a setup fee which is tracked as a second product:

Terminal

curl https://api.stripe.com/v1/products \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "name"="Starter Setup"

Create prices

Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions. Like products, if you only have a few prices it’s preferable to manage them in the Dashboard. Use the unit amount to express prices in the lowest unit of the currency—in this case, cents (10 USD is 1,000 cents, so the unit amount is 1000).

The price for the analytics dashboard is 10 USD per month. To create the price and assign it to the product, pass the product ID, unit amount, currency, and interval:

Terminal

curl https://api.stripe.com/v1/prices \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "product"="{{PRODUCT_ID}}" \
  -d "unit_amount"=1000 \
  -d "currency"="usd" \
  -d "recurring[interval]=month"

The setup fee for new customers is 20 USD. Because this charge is separate from the subscription and is only charged once, you don’t need to pass the interval:

Terminal

curl https://api.stripe.com/v1/prices \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "product"="{{PRODUCT_ID}}" \
  -d "unit_amount"=2000 \
  -d "currency"="usd"

After prices are created, you can only update their metadata, nickname, and active fields.

Create a customer

Before billing a customer, you need to create a Customer object that you can configure with a name, email, and payment method. You can read more about this in our subscription guide, but a basic example might look like this:

Terminal

curl https://api.stripe.com/v1/customers \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "email"="jenny.rosen@example.com" \
  -d "payment_method"="pm_card_visa" \
  -d "invoice_settings[default_payment_method]"="pm_card_visa"

Bill the customer

You can bill customers using invoices, subscriptions, or Checkout. Examples for each of these methods is explained below.

Using invoices

If you need to invoice a customer for a one-time charge like your setup fee, create an invoice item by passing the customer ID, currency, and price:

Terminal

curl https://api.stripe.com/v1/invoiceitems \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "price"="{{PRICE_ID}}"

You can then create an invoice for your customer and the invoice item will be added automatically:

Terminal

curl https://api.stripe.com/v1/invoices \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{{CUSTOMER_ID}}"

Using subscriptions

To create a subscription, combine a recurring price with a customer. If you would like to bundle one-time purchases with a recurring purchase, you can do so by using add_invoice_items:

Terminal

curl https://api.stripe.com/v1/subscriptions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "items[0][price]={{RECURRING_PRICE_ID}}" \
  -d "add_invoice_items[0][price]={{PRICE_ID}}"

This creates a 10 USD/month subscription for the prices analytics dashboard and charges a one-time set up fee of 20 USD. The customer will be charged 30 USD for their first month and then 10 USD each month after that.

You can also use add_invoice_items when updating subscriptions, including with pending updates. All invoice items configured in add_invoice_items will be created immediately. If the update results in an invoice, the invoice items will be included on that invoice. Otherwise, the invoice items will remain pending on the customer and will be picked up by the next invoice. If your business charges additional fees when upgrading to a new service, you would pass the price for that fee in add_invoice_items.

Using subscription schedules

Some of your customers may want to schedule their analytics dashboard service to start in the future or only sign up for a year of service at a time. Using subscription schedules, you can configure phases with a recurring price to start in the future and/or end on a particular date. If you would like to bundle one-time purchases with the beginning of a phase, you can do so by using add_invoice_items on a phase:

Terminal

curl https://api.stripe.com/v1/subscription_schedules \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d customer="{{CUSTOMER_ID}}" \
  -d start_date=1627776000 \
  -d "phases[0][items][0][price]={{RECURRING_PRICE_ID}}" \
  -d "phases[0][add_invoice_items][0][price]={{PRICE_ID}}"

This will schedule a 10 USD/month subscription to begin in the future and its first invoice will include a one-time fee of 20 USD.

If add_invoice_items is configured on future phases, invoice items will not be generated until that phase begins. If you set add_invoice_items on the current phase, invoice items will be generated immediately.

Using Checkout

Checkout creates a secure, Stripe-hosted payment page that lets you collect payments quickly. As a busy entrepreneur, you focus on improving your analytics dashboard product rather than your checkout flow.

A Checkout Session represents the details of your customer’s intent to purchase. You create a session when your customer wants to pay for something. After redirecting your customer to a Checkout Session, Stripe presents a payment form where your customer can complete their purchase. Once your customer has completed a purchase, they are redirected back to your site.

Checkout supports recurring and one-time purchases using prices:

Terminal

curl https://api.stripe.com/v1/checkout/sessions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d customer="{{CUSTOMER_ID}}" \
  -d "payment_method_types[]=card" \
  -d "line_items[0][price]={{PRICE_ID_1}}" \
  -d "line_items[0][quantity]=1" \
  -d "line_items[1][price]={{PRICE_ID_2}}" \
  -d "line_items[1][quantity]=1" \
  -d success_url="https://example.com/success" \
  -d cancel_url="https://example.com/cancel" \
  -d mode="payment"

Similar to the subscriptions example, this Checkout session creates a 10 USD/month subscription and charges a one-time fee of 20 USD. The customer will be charged 30 USD for their first month and then 10 USD each month after that. Note that Checkout doesn’t support sub-cent prices. For example, 0.001 USD and 10.00005 USD aren’t supported but prices like 1.10 USD and 0.75 USD are acceptable.

Ad-hoc prices

In some cases, you might want to use a custom price that has not been preconfigured. For example, donation sites often allow customers to specify the amount they want to donate. In this case, you’re offering a limited time promotion to “choose what you pay” for your analytics dashboard. You can pass in price_data instead of a price ID. For example, subscribing a customer to a monthly subscription with a custom price might look like this:

Terminal

curl https://api.stripe.com/v1/subscriptions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d customer="{{CUSTOMER_ID}}" \
  -d "items[0][price_data][unit_amount]=5000" \
  -d "items[0][price_data][currency]=usd" \
  -d "items[0][price_data][product]="{{PRODUCT_ID}}"
" \
  -d "items[0][price_data][recurring][interval]=month"

This creates an ad-hoc active=false recurring price of 50 USD for the Starter Dashboard product and creates a subscription with the new price. These ad-hoc prices cannot be updated once they have been created.

You can also pass price_data into the Checkout, Invoice Items, and Subscription Schedule APIs.

Products and Prices

Create a product

Create prices

Create a customer

Bill the customer

Using invoices

Using subscriptions

Using subscription schedules

Using Checkout

Ad-hoc prices

OptionalManaging prices