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.
Required scope: product.read (Read products).
query Parameters
scopeFilter by cost scope
Requests also accept the new spelling: each value in lower case (org for ORG). The listed spelling is deprecated in requests and accepted until 2026-11-30.
Filter 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.
Required scope: product.write (Write 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.
Locale-keyed overrides for the cost's description.
Create an org-scoped cost › Responses
Created
Get a cost
Returns one cost by id, whether it belongs to a product or to the organization. Retired costs are not returned. By default a product's cost shows its published value; view=draft shows the value in the product's working draft (what create and update answer), view=head returns only a cost its product has published, and product_version_id shows the value at one product version (not combined with view). An organization's cost has one live value in every view.
Required scope: product.read (Read products).
path Parameters
idCost UUID
query Parameters
viewValue view: draft (the working draft's value of a product's cost) or head (only a cost its product has published). Default: the published value.
product_version_idRead a product's cost at one product version. Not combined with view.
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. From 2026-11-30 DELETE removes only a cost no release ever carried, and a released cost answers 409: retire it with PATCH /costs/{id} {"status": "retired"}.
Required scope: product.write (Write products).
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 of a product's or an organization's cost. A value change (amount or expression) to a product's cost goes into the product's working draft and bills from the product's next publish; a value change to an organization's cost applies at once and republishes every active product that uses it (see GET /costs/{id}/consumers). Description, translations, metadata and requires_continuous_coverage apply at once. Send status alone to change it: retired takes a released cost out of the catalog (an organization's cost at once, a product's cost at the product's next release; a product's cost no release ever carried is a 409, DELETE removes it), active undoes a removal that has not been released yet. A cost already in the status sent is returned unchanged. Answers the cost as view=draft reads it.
Required scope: product.write (Write products).
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).
statusretired takes a released cost out of the catalog: an organization's cost at once, a product's cost at the product's next release (until then active undoes it). A product's cost no release ever carried is refused (409); DELETE removes it. active undoes a removal that has not been released yet: a product's cost goes back into the product's working draft with the head's value, an organization's cost becomes active again. Refused (409) when the product's head does not carry the key. Send status alone; a cost already in the status sent is returned unchanged.
Locale-keyed overrides for the cost's description.
Update a cost › Responses
OK
List products consuming a cost
Lists the products a value change to this cost reaches, as ProductRef. For an organization's cost: every active product whose published version uses the cost's key. For a product's cost: that product.
Required scope: product.read (Read products).
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
Deprecated: use PATCH /costs/{id} instead. Removed on 2026-11-30.
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. Replaced by PATCH /costs/{id} with {"status": "active"}.
Required scope: product.write (Write products).
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