A price defines the monetary amount charged for a product within a plan. Prices support multiple currencies, billing periods, and pricing models - from simple flat fees to complex tiered and formula-based calculations.
Pricing models:
- Flat - a fixed amount per billing period (e.g., $49/month)
- Per-unit - a fixed amount multiplied by quantity (e.g., $10/seat)
- Tiered - different rates at different volume thresholds (e.g., $0.10/unit for 0–1,000, $0.08/unit for 1,001–10,000)
- Volume - the tier that contains the total quantity determines the rate for all units
- Graduated - each tier's rate applies only to units within that tier's range
- Formula - a mathematical expression evaluated at billing time (see Price Formulas)
Key concepts:
- Effective date - prices can be scheduled to take effect in the future
- Country code - geo-specific pricing for different markets
- Currency - each price is denominated in a single currency; use multiple prices for multi-currency support
List prices
Returns a paginated list of prices. Supports the unified field.op=value filter grammar (see /docs/pagination).
query Parameters
limitPage size
cursorPagination cursor
product_idFilter by product UUID (sugar for product_id.eq); also supports product_id.in
plan_idFilter by plan UUID (sugar for plan_id.eq); also supports plan_id.in
statusFilter by status (sugar for status.eq); also supports status.ne, status.in
List prices › Responses
Paginated list with data and pagination envelope
archived_atcountry_codecreated_atcurrencycustomer_iddeleted_atdisplay_nameeffective_fromeffective_tohead_version_ididkindlist_priceorganization_idplan_idplan_versionprice_keyproduct_idrequires_continuous_coveragestatusupdated_atvalid_fromvalid_toversionCreate a price
Creates a new price. If FormulaID is not provided, a formula is auto-created from the Amount field.
Create a price › Request Body
country_codecurrencycustomer_iddisplay_nameM186 - customer-facing label
effective_fromeffective_tokindlist_priceplan_idplan_versionprice_keyproduct_idvalid_fromValidFrom / ValidTo are the customer-facing time bounds for an override ("this negotiated price applies until 2026-12-31"). Distinct from EffectiveFrom/EffectiveTo which are price-version publish/archive timestamps.
valid_toCreate a price › Responses
Wrapped in data envelope
archived_atcountry_codecreated_atcurrencycustomer_iddeleted_atdisplay_nameeffective_fromeffective_tohead_version_ididkindlist_priceorganization_idplan_idplan_versionprice_keyproduct_idrequires_continuous_coveragestatusupdated_atvalid_fromvalid_toversionResolve a price
Resolves the most specific price for the given dimensions.
Resolve a price › Request Body
at_price_version_idat_timecountry_codecurrencycustomer_idplan_idplan_versionPlanVersion narrows PLAN_OVERRIDE matching to overrides created for this exact plan version. Required when PlanID is set — the resolver returns an error otherwise. Sub-scoped callers pass sub.PlanVersion; catalog callers passing PlanID also pass the plan's current head version.
price_keyproduct_idquantitysubscription_idResolve a price › Responses
Wrapped in data envelope
Get a price
Returns a single price by UUID
path Parameters
idPrice UUID
Get a price › Responses
Wrapped in data envelope
archived_atcountry_codecreated_atcurrencycustomer_iddeleted_atdisplay_nameeffective_fromeffective_tohead_version_ididkindlist_priceorganization_idplan_idplan_versionprice_keyproduct_idrequires_continuous_coveragestatusupdated_atvalid_fromvalid_toversionUpdate a price
Updates an existing price by UUID
path Parameters
idPrice UUID
Update a price › Request Body
country_codecurrencydisplay_nameM186 - customer-facing label
effective_atADR-0006 edit-as-publish controls. effective_at and save_as_draft are mutually exclusive (400 on both).
effective_fromEffectiveFrom, when set, lands as the new price version's effective_from (and the prior head's effective_to). The scheduler injects scheduled_at here on release so a future-dated change produces a future-effective version row. Unset = now().
ADR-0006: EffectiveAt is the unified API name across all versioned entities. For the price entity it aliases EffectiveFrom — handlers fold EffectiveAt into EffectiveFrom before calling repo.Update so the scheduler-internal hot path keeps a single source of truth.
expected_versionlist_pricesave_as_draftTiers, when non-nil, replaces the tier set on the new price version. nil means "carry the previous version's tiers forward"; an empty slice means "this version has no tiers".
Update a price › Responses
Wrapped in data envelope
archived_atcountry_codecreated_atcurrencycustomer_iddeleted_atdisplay_nameeffective_fromeffective_tohead_version_ididkindlist_priceorganization_idplan_idplan_versionprice_keyproduct_idrequires_continuous_coveragestatusupdated_atvalid_fromvalid_toversionCopy a price as a new draft
Clones an existing price (active or archived) into a new active
path Parameters
idSource price UUID
Copy a price as a new draft › Responses
Wrapped in data envelope
archived_atcountry_codecreated_atcurrencycustomer_iddeleted_atdisplay_nameeffective_fromeffective_tohead_version_ididkindlist_priceorganization_idplan_idplan_versionprice_keyproduct_idrequires_continuous_coveragestatusupdated_atvalid_fromvalid_toversionList price versions (with lifecycle filter)
path Parameters
idPrice UUID
query Parameters
statusLifecycle status filter (repeatable)
List price versions (with lifecycle filter) › Responses
OK
archived_reasoncreated_atcreated_byeffective_fromeffective_toidID is the *_versions.id UUID. Phase 2.D needs it so the FE stage-mode chip can wire selection→pin map without a separate number→ID lookup; older clients can ignore the field.
published_atstatususage_countversionGet a price version snapshot
path Parameters
idPrice UUID
versionVersion number
Get a price version snapshot › Responses
OK
CostVersionPins maps each cost.
country_codecurrencycustomer_iddisplay_namesnapshot of prices.display_name at publish (M186)
effective_fromeffective_toFormulaVersionPins maps each tier.FormulaID referenced by this price-version's tiers to the price_formula_version_id active at publish time. Phase 2 of formula versioning (Phase 1 deref'd FormulaID to the current head; this lets replay use the historical formula version instead). Map key is formula_id stringified — same shape as cost_version_pins. Empty when no tier references a formula.
idkindlist_priceorganization_idplan_idprice_idprice_keyproduct_idpublished_atpublished_byversion