A product represents a billable item in your catalog - a feature, service, or resource that customers pay for. Products are the building blocks of plans and appear as line items on invoices.
Products can be recurring (charged every billing period), usage-based (metered and charged based on consumption), or one-time (charged once at purchase).
Key concepts:
- Product type -
recurring,usage,one_time, orseat- determines how charges are calculated - External ID - your internal SKU or product code for integration with other systems
- Cost tracking - named COGS entries via
costs[](per-product or org-scoped) for margin analysis - Dependencies -
requires_product_idsenforces that certain products must be purchased together
List products
Returns a paginated list of products. Supports the unified field.op=value filter grammar (see /docs/pagination) plus custom-field filters via the custom_fields.
query Parameters
limitPage size
cursorPagination cursor
typeFilter by product type (sugar for type.eq); also supports type.in
statusFilter by status (sugar for status.eq); also supports status.ne, status.in
invoiceable_standaloneFilter to products eligible for the manual-invoice picker (Phase 2.5 curation flag)
List products › Responses
Paginated list with data and pagination envelope
archived_atnamed cost variants (eager-loaded)
created_atdeleted_atdeprecated_atdescriptionexternal_idhead_version_ididinvoiceable_standaloneInvoiceableStandalone is the Phase 2.5 curation flag. When true, the product is eligible to appear in the manual-invoice product picker and the Phase 2 line resolver accepts it. When false (the default), the product is subscription-only / off-catalog and the resolver rejects attempts to put it on a manual invoice line. Edited live on the parent (Bucket-A); no version bump.
nameorganization_idpricing_modelpublic_descriptionpublished_atpublished_byrequires_continuous_coveragerequires_product_idsstatustax_categoryDEFAULT, REDUCED, ZERO, EXEMPT
typeupdated_atversionCreate a product
Creates a new product in draft status
Create a product › Request Body
descriptionexternal_idinvoiceable_standaloneInvoiceableStandalone opts the product into the manual-invoice picker on create. Defaults to false (subscription-only).
namepricing_modelpublic_descriptionrequires_product_idstax_categoryDEFAULT, REDUCED, ZERO, EXEMPT (defaults to DEFAULT)
typeCreate a product › Responses
Wrapped in data envelope
archived_atnamed cost variants (eager-loaded)
created_atdeleted_atdeprecated_atdescriptionexternal_idhead_version_ididinvoiceable_standaloneInvoiceableStandalone is the Phase 2.5 curation flag. When true, the product is eligible to appear in the manual-invoice product picker and the Phase 2 line resolver accepts it. When false (the default), the product is subscription-only / off-catalog and the resolver rejects attempts to put it on a manual invoice line. Edited live on the parent (Bucket-A); no version bump.
nameorganization_idpricing_modelpublic_descriptionpublished_atpublished_byrequires_continuous_coveragerequires_product_idsstatustax_categoryDEFAULT, REDUCED, ZERO, EXEMPT
typeupdated_atversionGet a product
Returns a single product by UUID
path Parameters
idProduct UUID
Get a product › Responses
Wrapped in data envelope
archived_atnamed cost variants (eager-loaded)
created_atdeleted_atdeprecated_atdescriptionexternal_idhead_version_ididinvoiceable_standaloneInvoiceableStandalone is the Phase 2.5 curation flag. When true, the product is eligible to appear in the manual-invoice product picker and the Phase 2 line resolver accepts it. When false (the default), the product is subscription-only / off-catalog and the resolver rejects attempts to put it on a manual invoice line. Edited live on the parent (Bucket-A); no version bump.
nameorganization_idpricing_modelpublic_descriptionpublished_atpublished_byrequires_continuous_coveragerequires_product_idsstatustax_categoryDEFAULT, REDUCED, ZERO, EXEMPT
typeupdated_atversionUpdate a product
Updates an existing product by UUID
path Parameters
idProduct UUID
Update a product › Request Body
ChildVersionPins, when non-nil, requests a new product_versions row whose pin maps embed the supplied child-version selections. Phase 2.D stage-mode publish path: the operator reviews drift in stage mode, picks a version per child (or accepts head), and the FE ships the resulting map here. Treated as a Bucket-B trigger by the repo — any non-nil value bumps products.version and inserts a fresh product_versions row. Missing children fall back to their heads via insertProductVersionTxWithPins's merge.
descriptioneffective_atADR-0006 edit-as-publish controls. effective_at and save_as_draft are mutually exclusive (400 on both). When both are nil/false, a versioned change publishes ACTIVE immediately; a bookkeeping-only change updates the header in-place.
expected_versionexternal_idinvoiceable_standaloneInvoiceableStandalone is the Phase 2.5 curation flag. Pointer so nil means "leave unchanged"; a non-nil bool flips the flag.
namepricing_modelpublic_descriptionrequires_product_idssave_as_draftstatustax_categoryUpdate a product › Responses
Wrapped in data envelope
archived_atnamed cost variants (eager-loaded)
created_atdeleted_atdeprecated_atdescriptionexternal_idhead_version_ididinvoiceable_standaloneInvoiceableStandalone is the Phase 2.5 curation flag. When true, the product is eligible to appear in the manual-invoice product picker and the Phase 2 line resolver accepts it. When false (the default), the product is subscription-only / off-catalog and the resolver rejects attempts to put it on a manual invoice line. Edited live on the parent (Bucket-A); no version bump.
nameorganization_idpricing_modelpublic_descriptionpublished_atpublished_byrequires_continuous_coveragerequires_product_idsstatustax_categoryDEFAULT, REDUCED, ZERO, EXEMPT
typeupdated_atversionDuplicate a product
Creates a new product whose attributes are copied from the source. Prices, costs and meter bindings on the source are NOT copied; only the product definition.
path Parameters
idSource product UUID
Duplicate a product › Responses
Created
archived_atnamed cost variants (eager-loaded)
created_atdeleted_atdeprecated_atdescriptionexternal_idhead_version_ididinvoiceable_standaloneInvoiceableStandalone is the Phase 2.5 curation flag. When true, the product is eligible to appear in the manual-invoice product picker and the Phase 2 line resolver accepts it. When false (the default), the product is subscription-only / off-catalog and the resolver rejects attempts to put it on a manual invoice line. Edited live on the parent (Bucket-A); no version bump.
nameorganization_idpricing_modelpublic_descriptionpublished_atpublished_byrequires_continuous_coveragerequires_product_idsstatustax_categoryDEFAULT, REDUCED, ZERO, EXEMPT
typeupdated_atversionList product versions (with lifecycle filter)
Returns version rows for a product. Default excludes DRAFT and CANCELLED.
path Parameters
idProduct UUID
query Parameters
statusLifecycle status filter (repeatable)
List product 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 product version snapshot
path Parameters
idProduct UUID
versionVersion number
Get a product version snapshot › Responses
OK
descriptioneffective_fromeffective_toexternal_ididmetadatanameproduct_idproduct_statusproduct_typepublished_atpublished_byrelease_strategystatusversion