Products & prices
Your catalog โ what you sell, and every way you can charge for it.
A Product is the thing you sell โ "Pro Plan", "Consulting Hour", "Widget". A Price says how much it costs and how it's billed. One product can have many prices.
How it works
- Create the Product first (name, description, metadata).
- Attach one or more Prices to it: one-time or recurring, flat, tiered (price changes with quantity), or usage-based (billed on reported usage via a Meter). Each Price also picks a currency, so the same Product can be priced separately per market.
- Retrieve a single Product by ID, or list every Product in the catalog.
Products and Prices are never charged directly โ they're referenced as line items on an Invoice or Subscription, which is what actually bills the customer.
Common use cases
- A SaaS plan sold monthly in THB and annually in USD โ one Product, four Prices.
- A metered API product billed per 1,000 calls โ a usage-based Price paired with a Meter that tracks reported usage.
- Volume pricing that gets cheaper per unit above 100 units โ a tiered Price.
Fractional unit prices
A usage-based Price can carry unit_amount_decimal: the price per unit, in the
currency's smallest unit, as a string with up to 12 decimal places. For example,
"0.04" means 0.04 satang per unit. Send it instead of amount
(sending both returns 400). The response returns it as a string.
{
"product": "prod_...",
"currency": "THB",
"unit_amount_decimal": "0.04",
"recurring": { "interval": "month", "interval_count": 1 },
"usage_based": { "event_name": "api_request" }
}A fractional unit_amount_decimal only works if the provider accepts
fractional unit prices. Stripe does. Other providers reject the Price with 400.