Products and prices in Stripe

This chapter follows Customers in Stripe.

Checkout Sessions and subscriptions reference Price ids (price_...), not free-form amounts in the client. That keeps your catalog auditable and stops tampered browsers from changing what someone pays.

Product versus Price

A Product is the thing you sell—name, description, images, tax category. A Price attaches billing terms: unit amount, currency, and whether billing is one-time or recurring.

One Product can have many Prices (monthly vs annual, USD vs EUR, legacy vs current rate).

1
import { stripe } from '../stripe-client.js';
2

3
const product = await stripe.products.create({
4
  name: 'Pro plan',
5
  description: 'Full access to the app',
6
});
7

8
const monthly = await stripe.prices.create({
9
  product: product.id,
10
  unit_amount: 2000,
11
  currency: 'usd',
12
  recurring: { interval: 'month' },
13
  lookup_key: 'pro_monthly_usd',
14
});
15

16
const lifetime = await stripe.prices.create({
17
  product: product.id,
18
  unit_amount: 19900,
19
  currency: 'usd',
20
  lookup_key: 'pro_lifetime_usd',
21
});
22

23
console.log({ productId: product.id, monthly: monthly.id, lifetime: lifetime.id });

Run seed scripts against test mode first. Production catalog changes usually go through review and Dashboard or infrastructure-as-code workflows.

One-time and recurring prices

Trials and usage-based components attach at subscription or Price level; see Subscriptions in Stripe.

Why prices are immutable

You cannot change unit_amount or currency on an existing Price. Stripe treats a Price as a historical record—active subscriptions must keep billing the terms they started on.

To raise prices:

1. Create a new Price on the same (or new) Product.
2. Point new Checkout Sessions at the new Price id.
3. Migrate existing subscribers with proration rules (subscription update APIs or Customer Portal).

Deactivate old Prices with active: false so they no longer appear in Dashboard pickers but existing subscriptions keep working.

Lookup keys and catalog resolution

lookup_key is a stable string you choose (for example pro_monthly_usd). At runtime, resolve it to the current Price id so deploys do not hard-code price_... strings:

1
const prices = await stripe.prices.list({
2
  lookup_keys: ['pro_monthly_usd'],
3
  active: true,
4
  limit: 1,
5
});
6
const priceId = prices.data[0]?.id;

Keep lookup keys unique per mode. Document which key each environment uses in config, not in the client.

Dashboard, API, and tax behavior

Many teams create Products in the Dashboard during early development, then move to seed scripts or Stripe’s product export/import for staging parity.

Tax behavior on a Price (exclusive, inclusive, or unspecified) interacts with Stripe Tax. Enabling automatic tax without registrations collects nothing while looking enabled—a common misconfiguration. Configure registrations before turning on automatic_tax in Checkout.

Archiving and displaying catalog in your app

List active Products with expanded default prices for a pricing page:

1
const products = await stripe.products.list({ active: true, limit: 20 });
2
const prices = await stripe.prices.list({ active: true, product: products.data[0].id });

Your marketing site can cache this JSON; payment flows should still verify Price ids on the server when creating Checkout Sessions.

Next: Accepting payments with Stripe Checkout.