A reservation places a hold on a customer's wallet, reserving funds for a unit of work that is later captured (settled) or released. This is the reserve → capture → release lifecycle - the authorize/capture pattern applied to wallet balance. Reservations are the primary money-gating surface for prepaid usage.
Reserve wallet funds
Resolves the price for the requested product and places a hold on the customer's wallet - a reservation. Capture or release follow at /reservations/{id}/capture or /reservations/{id}/release. Insufficient balance and wallet-currency mismatches are NOT errors: they return 201 with can_proceed=false and the cause in blocked_reasons.
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.
Reserve wallet funds › Request Body
customer_idCustomer whose wallet the hold reserves against.
Named dimension values used to select a dimensional price tier.
external_cost_amount^-?\d+(\.\d+)?$Caller-supplied wholesale cost fed to the price formula's cost.* variables, MAJOR units; requires external_cost_currency.
external_cost_currencyISO 4217 currency of external_cost_amount; must match the price's native currency.
hold_expires_atTTL of the created hold; the wallet auto-releases it if not captured by this instant. Null uses the server default window.
idempotency_keyCaller key that collapses retries of the same reserve to one hold.
Arbitrary caller-supplied key/value annotations carried on the reserve outcome.
metric_keyMetric being consumed; must match the product's meter binding.
price_keySelects a specific price when the product exposes keyed prices; null uses the default.
Named numeric variables bound into the price formula at resolve time.
product_idMetered product being consumed; drives price resolution.
quantity^-?\d+(\.\d+)?$Number of metric units to reserve; must be greater than zero.
subscription_idSubscription the usage is charged under.
wallet_currencyPins the hold to the customer's wallet in this ISO 4217 currency; null uses their primary wallet.
Reserve wallet funds › Responses
Created
Capture (settle) a reservation
Settles a pending reservation by debiting the reserved funds. Use after the work that triggered the reservation has succeeded.
path Parameters
idHold UUID
Hold 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.
Capture (settle) a reservation › Request Body
amount^-?\d+(\.\d+)?$Partial-capture amount, MAJOR units, in the hold's currency. Omitted: captures the full held amount.
referenceOptional external reference recorded on the capture's ledger entry.
Capture (settle) a reservation › Responses
OK
Release a reservation
Releases a pending reservation, returning reserved funds to available balance. Use when the work that triggered the reservation was cancelled or failed.
path Parameters
idHold UUID
Hold 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.
Release a reservation › Responses
OK