Price the way your product is sold
Attach recurring or one-time prices to a product, with their currency and pricing model. The product defines the offer; its prices define how the customer pays for it.
Example — Offer monthly and yearly billing
A professional plan costs $29 per month or $290 per year. Both prices refer to the same product and its benefits.
For engineers
This is the professional plan’s monthly price from Wonder Todos. It is a selected member of the product’s prices array:
The following selected excerpt is from product.ts; the surrounding module and explanatory source comments are omitted.
model: PricingModel.FLAT,
unitPrice: { amount: 2900n, decimals: 2, currency: AvailableCurrency.USD },
interval: BillingInterval.MONTH,
intervalCount: 1,
isDefault: true,
amount: 2900n with decimals: 2 means 29.00 USD. The integer is not the display amount. The yearly alternative uses 29000n and BillingInterval.YEAR. Resolve a price belonging to the selected product; checkout rejects mismatched product/price pairs.
A recurring price combines interval with intervalCount: MONTH with 3 bills every three months; an omitted count defaults to 1. Catalog sync preserves that cadence in the local price and the provider request. A one-time price has no recurring interval. Existing provider-linked prices are not automatically rewritten when a declaration changes.
Match the model to provider behavior
The price schema describes flat, per-unit, tiered, graduated and package models. Tier rows carry an upper bound and unit/flat amounts; an open-ended final bound uses null. Metered consumption still needs the application to record usage. Declaring a per-unit price does not measure activity.
The sync service converts every amount from its authored scale into the currency’s minor units before calling the provider. It rejects an amount that cannot be represented exactly rather than rounding the charge. For example, a sub-cent authored USD amount cannot be treated as a whole cent merely because its integer is 1n. Inspect synchronization errors and use a representable commercial unit.
Each price carries its own currency. Global defaultCurrency and supportedCurrencies record commercial intent but do not validate or rewrite price currencies. Changing a stored price also requires confirming the provider price mapping and the treatment of existing subscribers; provider-linked prices are not a promise that every later edit creates a replacement provider price.