Rate tables provide structured lookup pricing - a grid of rates indexed by one or more dimensions. Use rate tables for complex pricing that depends on multiple variables like geography, volume tier, customer segment, or contract term.
Example: A shipping rate table with dimensions for weight range, origin country, and destination country.
List rate tables
Lists all rate tables that belong to the caller's organization.
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.
sortOrdering: slug, name or created_at, each with an optional :asc/:desc suffix (default slug:asc). An unknown value is rejected. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page.
has_scheduled_versionFilter by whether the entity has a version scheduled to publish (true or false). A scheduled version is a FROZEN version row a pending catalog.publish_version Change is bound to; the entity itself stays draft, published or archived and its working draft stays free for immediate changes.
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 rate tables › Responses
OK
Create a rate table
Creates a new rate-table container scoped to the caller's organization. Versions and entries are added through the version sub-routes.
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 rate table › Request Body
nameDisplay name for the table.
on_missing_keyBehaviour when no entry matches: 'error', 'zero', or 'default_value'.
slugURL-safe unique identifier formulas reference this table by.
table_typeMatching mode: 'lookup' (exact key match) or 'bracket' (numeric range match).
currencyISO 4217 currency for the entry values; defaults to the org's preferred currency when omitted.
default_valueDecimal value returned on a miss; required when on_missing_key=default_value.
descriptionOptional description of the table's purpose.
requires_continuous_coverageWhen true, published versions may not leave a gap in the effective-date timeline.
Create a rate table › Responses
Created
Get a rate table
Returns the rate table's root row (slug, type, missing-key policy, currency, lifecycle status, head version pointer). Version content — the rows and entries — is served by the /rate-tables/{id}/versions endpoints.
path Parameters
idRate table ID
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 rate table › Responses
OK
Delete a rate table (draft only)
Hard-deletes a rate table that has never had a published version. Once a version is published, use Archive instead.
path Parameters
idRate table ID
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.
Delete a rate table (draft only) › Responses
No Content
Update a rate table
Updates editable fields on a rate table (name, description, etc.). With effective_at set, takes the table's latest draft version live — immediately or scheduled — and returns the affected version instead of the table.
path Parameters
idRate table ID
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 rate table › Request Body
default_valueNew default value; omit to leave unchanged.
descriptionNew description; omit to leave unchanged.
nameNew display name; omit to leave unchanged.
on_missing_keyNew missing-key behaviour ('error', 'zero', or 'default_value'); omit to leave unchanged.
requires_continuous_coverageNew continuous-coverage requirement; omit to leave unchanged.
Update a rate table › Responses
OK
Archive a rate table (terminal)
Terminal transition: soft-deletes the table and archives all of its versions, returning 200 with the archived rate table. Use this once the table has at least one published version (Delete is reserved for never-published drafts).
path Parameters
idRate table ID
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.
Archive a rate table (terminal) › Responses
OK
Get the staged draft
The entity's open draft: its row id (the same id catalog.publish_version binds as staged_version_id), the version number it will publish as, when it was opened and last touched, the head version it forks from, and a counted summary of what is staged. 404 when nothing is staged — which is a state, not an error.
path Parameters
idThe entity's 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 the staged draft › Responses
OK
Discard the staged draft
Throws the staged draft away. The live entity is untouched: nothing pointed at the draft and it was never on the billing timeline. 404 when nothing is staged, which is a different answer from a successful discard and is reported as one.
path Parameters
idThe entity's 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.
Discard the staged draft › Responses
No Content
List rate-table versions (with lifecycle filter)
Returns version rows for the entity, keyset-paginated (default 100, max 200 per page). The status filter accepts draft, scheduled, published, archived; the default excludes draft (ADR-0007). Supports ?include=usage_count and ?archived_reason=.
path Parameters
idEntity UUID
query Parameters
statusLifecycle status filter (repeatable / comma-separated): draft, scheduled, published, archived. Default excludes draft.
archived_reasonNarrow archived rows by reason (repeatable / comma-separated): canceled, discarded, errored, superseded
includeComma-separated includes. Currently supports usage_count.
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 rate-table versions (with lifecycle filter) › Responses
OK
Create a draft rate-table version
Creates a new draft version under the given rate table. Entries must be added separately via the import endpoint before the version can be published. Returns 409 while another draft is open - a table has at most ONE open draft, because publish-with-effective_at always takes the latest one.
path Parameters
idRate table ID
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 draft rate-table version › Request Body
Bracket entries to create for the version.
clone_from_version_idOptional existing version to seed the new version's entries from.
effective_fromWhen the new version starts being effective on the billing timeline. Optional: the publish that takes the draft sets it; omitted, the draft is stamped with the request instant.
effective_toOptional timestamp at which the new version stops being effective.
Raw entry rows (lookup or bracket) for the version.
Lookup entries to create for the version.
release_nameOptional name for the version, shown beside its number.
release_noteOptional note describing the version.
Create a draft rate-table version › Responses
Created
Get the currently active rate-table version
Returns the rate-table version that is active at the current wall-clock time.
path Parameters
idRate table ID
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 the currently active rate-table version › Responses
OK
Get a rate-table version snapshot
Maps the version number to its version row and returns the full snapshot, including the version's rows and entries.
path Parameters
idEntity UUID
versionVersion number
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 rate-table version snapshot › Responses
OK
Delete a draft rate-table version
Hard-deletes a rate-table version, addressed by its version number (the same key GET /rate-tables/{id}/versions/{version} returns). Only allowed on draft versions; active or archived versions are immutable - archive them instead.
path Parameters
idRate table ID
versionVersion number
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.
Delete a draft rate-table version › Responses
No Content
Name or annotate a rate-table version
Sets the version's release_name and/or release_note. These are display metadata, not content: editing them never creates a new version and is allowed on published versions. An absent field is left unchanged; an empty string clears it.
path Parameters
idEntity UUID
versionThe version number
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.
Name or annotate a rate-table version › Request Body
release_nameNew name; empty string clears it. Absent leaves it unchanged.
release_noteNew note; empty string clears it. Absent leaves it unchanged.
Name or annotate a rate-table version › Responses
OK
created_ateffective_fromeffective_toidoriginWho made this version: manual (an operator published it), scheduled_release (a scheduled publish fired), cascade (republished automatically because something it depends on published).
published_atstatusversionarchived_reasonFor origin=cascade: the version whose publish caused this one, resolved to its entity and number.
created_byrank1-based position in the entity's queue of scheduled versions — the order they will fire. Present only on scheduled rows.
release_nameOperator-given name of this version, shown beside its number.
release_noteFree-text note about this version.
scheduled_change_idThe pending catalog.publish_version Change that will publish this version — reschedule or cancel it there.
scheduled_forWhen this scheduled version is due to publish. Present only on the row a pending catalog.publish_version Change is bound to.
usage_countArchive a rate-table version
Terminal transition - archived versions cannot be edited or re-activated, addressed by version number (the same key GET /rate-tables/{id}/versions/{version} returns). Use the copy endpoint to spin a new draft from an archived one.
path Parameters
idRate table ID
versionVersion number
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.
Archive a rate-table version › Responses
No Content
Copy a rate-table version into a new draft
Creates a new draft version cloned from the named source (any status), addressed by version number (the same key GET /rate-tables/{id}/versions/{version} returns). Entries are duplicated. Used to revive archived versions or to branch a new edit from an already-active version. Returns 409 while another draft is open - discard or publish it first.
path Parameters
idRate table ID
versionSource version number
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.
Copy a rate-table version into a new draft › Request Body
effective_fromEffective-from timestamp for the new draft version.
effective_toOptional effective-to timestamp for the new draft version.
release_nameOptional name for the new draft version.
release_noteOptional note for the new draft version.
Copy a rate-table version into a new draft › Responses
Created
Export rate-table version entries as CSV
Streams the version's entries as CSV with columns lookup_key, range_min, range_max, value, addressed by version number (the same key GET /rate-tables/{id}/versions/{version} returns). Suitable for round-tripping back through the import endpoint.
path Parameters
idRate table ID
versionVersion number
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.
Export rate-table version entries as CSV › Responses
CSV body
Import entries into a draft rate-table version
Replaces the draft version's entries with the supplied list (full replace, not merge), addressed by version number (the same key GET /rate-tables/{id}/versions/{version} returns). After importing, the version can be published or scheduled.
path Parameters
idRate table ID
versionVersion number
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.
Import entries into a draft rate-table version › Request Body
Import entries into a draft rate-table version › Responses
OK
Forecast the impact of superseding this rate-table version
Who is using the version in force today, and what a publish over it would move. pinnable reports whether holding a version is possible for this entity at all — it is false for tax rules, which are dated rather than pinned, so a caller must not render a pinned count for them. republishes_consumers is the cross-entity fan-out (publishing a price formula republishes every ACTIVE product whose head tiers reference it), and live_readers counts consumers billing off the live head, who move as soon as the publish lands. Read-only, and uncached: this is read at the moment money changes.
path Parameters
idEntity UUID
versionVersion number (positive integer)
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.
Forecast the impact of superseding this rate-table version › Responses
OK
List rate-table version referrers
Offset-paginated drill-down of the referrers of one type for one version of the entity.
path Parameters
idEntity UUID
versionVersion number (positive integer)
query Parameters
typeReferrer type to list (required)
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 rate-table version referrers › Responses
OK
Get rate-table version usage summary
Referrer counts for one version of the entity, grouped by referrer type. Powers the version-switcher hover card.
path Parameters
idEntity UUID
versionVersion number (positive integer)
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 rate-table version usage summary › Responses
OK