Product and org-scoped cost definitions consumed by pricing formulas.
List costs (org-wide)
Returns a paginated list of every active cost in the organization. Use scope=ORG to fetch only org-scoped costs (shared upstream fees) and scope=PRODUCT for the cross-product roll-up.
query Parameters
scopeFilter by cost scope
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List costs (org-wide) › Responses
OK
Create an org-scoped cost
Creates an ORG-scoped cost — used for shared upstream fees (payment processor, registry, etc.) that span multiple products.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create an org-scoped cost › Request Body
keyFormula-reference key for the new cost; 1-64 chars matching [a-zA-Z0-9._-].
Static money value; set exactly one of amount or expression.
descriptionOperator-facing description of what this cost represents.
Formula referencing other costs by key; set exactly one of amount or expression.
Free-form operator key/value metadata.
product_idOwning product for a PRODUCT-scoped cost, stamped from the URL path; null creates an ORG-scoped cost.
Locale-keyed overrides for the cost's description.
Create an org-scoped cost › Responses
Created
Get a cost
Scope-agnostic detail read: serves both PRODUCT- and ORG-scoped costs by cost id. Retired costs are not served.
path Parameters
idCost UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a cost › Responses
OK
Remove a cost
Removes the cost. A PRODUCT-scoped cost is removed in the owning product's working draft and leaves billing at the release that carries the removal; discarding the draft puts it back, and every published version goes on carrying the key it billed. A never-released PRODUCT cost is hard-deleted. An ORG-scoped cost has no product version to fall out of, so it is retired directly and every consuming product re-snapshots without it. Returns 204; an unknown cost is 404.
path Parameters
idCost UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Remove a cost › Responses
No Content
Update a cost
Merge-patch update, scope-agnostic. Value changes (amount, expression) are versioned: they accept the effective_at / save_as_draft publish controls, and saving an ORG-scoped cost's value republishes every ACTIVE product consuming it (see /costs/{id}/consumers). Display-only edits (description, translations, metadata) apply immediately and reject publish controls.
path Parameters
idCost UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Update a cost › Request Body
Replacement static money value; set at most one of amount or expression.
descriptionNew operator-facing description; null leaves it unchanged.
Replacement formula referencing other costs by key; set at most one of amount or expression.
Free-form operator key/value metadata.
requires_continuous_coverageFlips the continuous-coverage requirement live without touching the billing value; null leaves it unchanged.
save_as_draftRefused. A cost has no draft of its own: it is a child of its product and goes live with that product's next publish (POST /v1/changes, catalog.publish_version).
Locale-keyed overrides for the cost's description.
Update a cost › Responses
OK
List products consuming a cost
The consumer census. For an ORG-scoped cost: every ACTIVE product whose head version materialized the cost's key. For a PRODUCT-scoped cost: the owning product.
path Parameters
idCost UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List products consuming a cost › Responses
OK
Restore a removed cost
Undoes a removal that has not been released yet: a PRODUCT cost is added back to the owning product's working draft, on the same id and with the head's value; an ORG cost, whose removal was a direct flip, is made active again. Refused (409) when the current head does not carry the key.
path Parameters
idCost UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Restore a removed cost › Responses
OK
List costs for a product
Lists the costs visible to one product. Values come from the published head by default; ?view=draft serves the product's open working-draft values, ?view=head restricts to published-only rows, and ?product_version_id pins values to one historical product version (mutually exclusive with view).
path Parameters
idProduct UUID
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
viewValue view: draft (working-draft values) or head (published only)
product_version_idPin values to a product version
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List costs for a product › Responses
OK
Create a product-scoped cost
Creates a PRODUCT-scoped cost owned by the product in the URL — the URL determines scope; use POST /costs for shared ORG-scoped costs. The value reaches billing when the product is next published.
path Parameters
idProduct UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create a product-scoped cost › Request Body
keyFormula-reference key for the new cost; 1-64 chars matching [a-zA-Z0-9._-].
Static money value; set exactly one of amount or expression.
descriptionOperator-facing description of what this cost represents.
Formula referencing other costs by key; set exactly one of amount or expression.
Free-form operator key/value metadata.
product_idOwning product for a PRODUCT-scoped cost, stamped from the URL path; null creates an ORG-scoped cost.
Locale-keyed overrides for the cost's description.
Create a product-scoped cost › Responses
Created