Product and Price

A Product is the catalog entry for something you sell — a plan, a feature pack, a one-off SKU. A Price is a specific monetary amount + currency + recurrence attached to a product. A product may have many prices (currency variants, monthly vs. yearly, grandfathered tiers); subscriptions and invoices charge against a Price ID, never a Product ID.

Lifecycle

1. Create the product with createProduct. active: true makes it usable for new prices and checkouts.
2. Create one or more prices with createPrice, passing the product_id. Prices are immutable in terms of unit_amount, currency, and recurrence — to change the amount, create a new price and migrate subscriptions.
3. Set a default by patching default_price_id on the product so checkouts and the customer portal can resolve a single price per product.
4. Archive with archiveProduct or archivePrice when retired. Archived products and prices remain valid on existing subscriptions but cannot be selected for new ones.

Relationships

A PriceData belongs to one ProductData (product_id). Subscriptions reference prices through SubscriptionItem.price_id. Invoice line items can link to a price_id for catalog-driven invoicing or use raw unit_price + description for ad-hoc lines. Coupons may scope to specific products via applies_to_products.

Fields that matter

• Product name (string) and description (string) — surfaced on hosted invoices, checkouts, and the customer portal.
• Product default_price_id (string) — the price used when callers don't specify one (e.g. customer portal plan switcher).
• Price unit_amount (number, smallest currency unit — cents) and currency (CurrencyCode) — what gets charged per unit.
• Price recurring (boolean) — true requires interval (day | week | month | year) and interval_count; false is a one-time price suitable for invoices and checkouts.
• Price pricing_model (PricingModel) — per_unit, tiered_volume, tiered_graduated, package, metered, or flat_rate. metered requires usage reports (see Meter usage).
• Price trial_period_days (number) — applies a default trial when the price is used to start a subscription without an explicit trial_period_days override.

Related

• API reference: Products
• API reference: Product (price)
• Guide: Create a subscription