Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 38 ยท Subscriptions and Billing

Products and Prices: Modelling What You Sell

Model your catalog with Stripe Products and Prices. Learn one-time and recurring prices, billing intervals, tiered and volume pricing, lookup keys and how to compute totals for each model.

Before you can bill anyone repeatedly you need a clean description of what you sell and what it costs. Stripe splits that into two objects that beginners often blur together: a Product says what is sold, and one or more Prices say how much and how often. Getting this model right early makes subscriptions, upgrades, discounts and tax far simpler later.

Product versus Price

  • Product (prod_...): a name, description, images and metadata. "Pro plan" or "Beginner e-book". It has no amount.
  • Price (price_...): belongs to one product and fixes unit_amount, currency, and (for subscriptions) a recurring interval. "Pro plan, $29 per month" and "Pro plan, $290 per year" are two prices on one product.

Prices are immutable in the ways that matter: you cannot change the amount of an existing price. To change pricing you create a new price and archive the old one (active: false). Existing subscribers stay on the old price until you move them, which protects them from surprise bills and gives you grandfathering for free.

JavaScript
// Real Stripe usage (read-only).
const product = await stripe.products.create({
  name: "Pro plan",
  description: "Everything in Basic plus team features",
  metadata: { feature_set: "pro" },
});

const monthly = await stripe.prices.create({
  product: product.id,
  unit_amount: 2900,
  currency: "usd",
  recurring: { interval: "month" },
  lookup_key: "pro_monthly",
});

const yearly = await stripe.prices.create({
  product: product.id,
  unit_amount: 29000,
  currency: "usd",
  recurring: { interval: "year" },
  lookup_key: "pro_yearly",
});

Lookup keys

Hard-coding price_1Ox9... IDs in code is fragile, because test and live modes have different IDs. A lookup_key is a stable name you choose (pro_monthly); fetch prices by it with stripe.prices.list({ lookup_keys: ["pro_monthly"] }). The same code then works in both modes, and you can move a key to a new price (transfer_lookup_key: true) when you change pricing.

One-time and recurring

  • A price without recurring is one-time: used for single purchases in Checkout and invoices.
  • A price with recurring has an interval (day, week, month, year) and optional interval_count (every 3 months = quarterly). Recurring prices also choose usage_type: licensed (fixed quantity, like seats) or metered (billed on reported usage, covered in a later lesson).

Product and Price

Product What you sell
Price Amount and interval
Lookup key Stable name in code
1 / 2

Pricing models

Beyond a flat amount, Stripe supports more models through billing_scheme: "tiered":

Model How the total is computed Example
Per unit (per_unit) unit_amount x quantity $10 per seat
Graduated tiers Each tier's units priced at that tier's rate, then summed First 10 at $10, next 40 at $8
Volume tiers All units priced at the single tier the total falls into 1-10 at $10 each; 11-50 at $8 each
Package Price per block of N units $5 per 100 emails

The difference between graduated and volume trips people up, so compute both. Tier edges are inclusive of up_to.

Node.js Graduated versus volume pricing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Volume pricing creates a surprising effect at the edge (11 units can cost less than 10 under some tier designs), so plot your totals before you publish a price list.

Annual discounts and currencies

A common pattern is a yearly price equal to about ten or eleven monthly payments. Compute and show the saving honestly. A price can also carry currency_options, giving local prices for several currencies on one price object, instead of converting a USD price at checkout and showing an odd-looking number.

Node.js Compare monthly and yearly plans

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Keeping Stripe and your app in sync

Your app needs to know which features a plan grants. Do not put entitlement logic in the price amount. Store it in metadata on the product (for example feature_set: "pro") or, better, in your own database keyed by the lookup_key. Stripe's Entitlements feature can also map products to features for you.

Create products and prices with a script checked into your repository, so test and live catalogs match and a new developer can rebuild test mode in one command. The Dashboard is fine for experimenting.

Next: put a price to work with The Subscription Lifecycle.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You want to change your Pro plan from $29 to $39 a month. What do you do?

    A price's amount cannot be edited. New price plus archive keeps existing subscribers on the old price until you move them.
  2. 2. Which pricing model charges ALL units at the rate of the tier the total quantity falls into?

    Volume pricing applies one tier's rate to every unit; graduated prices each slice separately.
  3. 3. Why use a lookup_key?

    Lookup keys avoid hard-coding price IDs that differ between modes.
  4. 4. What distinguishes a recurring price from a one-time price?

    The recurring object (interval, interval_count, usage_type) makes a price billable repeatedly.

Summary

  • Products describe what you sell; Prices fix amount, currency and billing interval.
  • Prices are immutable: create new, archive old, grandfather subscribers.
  • Use lookup keys instead of hard-coded price IDs.
  • Per-unit, graduated, volume and package models compute totals differently; test the edges.
  • Keep feature entitlements in your own data or metadata, and script catalog creation.

Next: The Subscription Lifecycle