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, which answer the hold. include=hold adds that hold to this answer, in the same shape. Insufficient balance and wallet-currency mismatches are not errors: they return 201 with can_proceed=false and the cause in blocked_reasons.
Required scope: wallet.write (Operate wallets).
query Parameters
includeExtra data to add to the response: hold. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.
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.
metric_keyMetric being consumed; must match the product's meter binding.
product_idMetered product being consumed; drives price resolution.
quantity^-?\d+(\.\d+)?$ · requiredNumber of metric units to reserve; must be greater than zero.
subscription_idSubscription the usage is charged under.
Named dimension values used to select a dimensional price tier.
Caller-supplied wholesale cost fed to the price formula's cost.* variables, {value, currency}; its currency must be 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.
Arbitrary caller-supplied key/value annotations carried on the reserve outcome.
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.
wallet_currencyPins the hold to the customer's wallet in this currency; null uses their primary wallet.
idempotency_keyIgnored: the Idempotency-Key header is what collapses retries of the same reserve to one hold. Deprecated: use the Idempotency-Key header instead. Removed on 2026-11-30.
Reserve wallet funds › Responses
Created
Capture (settle) a reservation
Settles a pending reservation by debiting the reserved amount from the wallet's cash balance; price-reduction credit is never spent. Use after the work that triggered the reservation has succeeded.
Required scope: wallet.write (Operate wallets).
path Parameters
idHold 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
Partial-capture amount, {value, currency}, 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.
Required scope: wallet.write (Operate wallets).
path Parameters
idHold 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