Release a reservation · Ownrecord docs

Gives what a reservation still holds back to the wallet (each part to the credits it came from) and closes it as released. Releasing a released reservation returns it unchanged; a captured or expired one can't be released (reservation_not_open). Releasing changes no balance: the credits only stop being held.

At a glance

REST: POST /api/v1/reservations/{id}/release
MCP tool: reservations_release
Operation ID: reservations.release
Scope: Brand
Permission: wallets:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the wallets:write scope
Since: M6

Request

Path parameters

Field	Type	Description
`id`	`res_…` ID	The reservation (`res_…`).

Body

This operation takes no body.

Response

200 OK with a JSON object:

Field	Type	Description
`id`	string
`object`	`"reservation"`
`brandId`	`brd_…` ID
`livemode`	boolean
`walletId`	`wal_…` ID
`kind`	one of `single`, `lease`	`single` (§17.2) or `lease` (§17.3).
`status`	one of `active`, `expired_pending`, `captured`, `released`, `expired`	`active`, `captured`, `released`, `expired` (or `expired_pending` for leases).
`amount`	money	What was reserved.
`captured`	money	What was captured so far.
`outstanding`	money	What is still held: `amount − captured` while open, zero once closed.
`expiresAt`	date-time
`closedAt`	date-time or null
`idempotencyKey`	string
`metadata`	object
`createdAt`	date-time
`updatedAt`	date-time

Examples

The job was cancelled

HTTP

POST /api/v1/reservations/res_01m4ty7w2a5qx7mhd9k8w6s0b4/release
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14

Response (200):

JSON

{
  "id": "res_01m4ty7w2a5qx7mhd9k8w6s0b4",
  "object": "reservation",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "walletId": "wal_01m4ty7w2a5qx7mhd9k8w6s0b1",
  "kind": "single",
  "status": "released",
  "amount": {
    "amount": "3000000",
    "currency": "EUR"
  },
  "captured": {
    "amount": "0",
    "currency": "EUR"
  },
  "outstanding": {
    "amount": "0",
    "currency": "EUR"
  },
  "expiresAt": "2026-10-16T10:20:00.000Z",
  "closedAt": "2026-10-16T10:16:00.000Z",
  "idempotencyKey": "job-8841",
  "metadata": {
    "job": "8841"
  },
  "createdAt": "2026-10-16T10:15:00.000Z",
  "updatedAt": "2026-10-16T10:16:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`id` isn't a reservation ID (`res_…`).	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	This brand has no such reservation in this mode.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`reservation_not_open`	409	The reservation was already captured or expired.	Create a new reservation. A reservation is closed once it is captured, released or expired (`details.status`).
`version_conflict`	409	The wallet changed at the same moment (another reservation, capture or grant); retry.	Fetch the object again and retry the change.
`scope_required`	400	The request names no brand (an org or entity key without `Ownrecord-Brand`).	Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`).
`permission_denied`	403	You can't change this brand's wallets (`wallets:write`: owners, admins and support).	Ask an organization owner or admin for a role or scope that allows this action.
`livemode_not_allowed`	403	You have no live-mode access, so you can't use live wallets.	Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

The job was cancelled#

Errors#