List a wallet's reservations
The reservations.list operation: GET /api/v1/wallets/{id}/reservations in the REST API and the reservations_list tool in the MCP server.
GET
/api/v1/wallets/{id}/reservationsLists a wallet's reservations, newest first: single reservations and leases (kind), open and closed.
status=active: what holds funds now (withexpired_pendingfor leases waiting for a late settle);kind:singleorlease.
Paginate with limit (1–100, default 10) and starting_after (a res_… or lease_… ID).
At a glance
- REST:
GET /api/v1/wallets/{id}/reservations - MCP tool:
reservations_list - Operation ID:
reservations.list - Scope: Brand
- Permission:
wallets:read - Risk tier:
read - Dry run: Not supported
- Idempotency: Not needed (read only)
- Modes: Test and live
- Pagination:
limit(at most 100) andstarting_after - Authentication: API key with the
wallets:readscope - Since: M6
Request
Path parameters
| Field | Type | Description |
|---|---|---|
id | wal_… ID | The wallet (wal_…). |
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
limit | integer (1 to 100) | No | |
starting_after | string | No | |
status | one of active, expired_pending, captured, released, expired | No | Only reservations with this status. |
kind | one of single, lease | No | single reservations or leases (spec §17.3); both by default. |
Response
200 OK with a JSON object, a page of the list (newest first):
| Field | Type | Description |
|---|---|---|
object | "list" | |
data | array of object | |
data[].id | string | |
data[].object | "reservation" | |
data[].brandId | brd_… ID | |
data[].livemode | boolean | |
data[].walletId | wal_… ID | |
data[].kind | one of single, lease | single (§17.2) or lease (§17.3). |
data[].status | one of active, expired_pending, captured, released, expired | active, captured, released, expired (or expired_pending for leases). |
data[].amount | money | What was reserved. |
data[].captured | money | What was captured so far. |
data[].outstanding | money | What is still held: amount − captured while open, zero once closed. |
data[].expiresAt | date-time | |
data[].closedAt | date-time or null | |
data[].idempotencyKey | string | |
data[].metadata | object | |
data[].createdAt | date-time | |
data[].updatedAt | date-time | |
has_more | boolean | |
next_cursor | string or null |
Examples
Open reservations
HTTP
GET /api/v1/wallets/wal_01m4ty7w2a5qx7mhd9k8w6s0b1/reservations?status=active
Authorization: Bearer or_test_…
Response (200):
JSON
{
"object": "list",
"data": [
{
"id": "res_01m4ty7w2a5qx7mhd9k8w6s0b4",
"object": "reservation",
"brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
"livemode": false,
"walletId": "wal_01m4ty7w2a5qx7mhd9k8w6s0b1",
"kind": "single",
"status": "active",
"amount": {
"amount": "3000000",
"currency": "EUR"
},
"captured": {
"amount": "0",
"currency": "EUR"
},
"outstanding": {
"amount": "3000000",
"currency": "EUR"
},
"expiresAt": "2026-10-16T10:20:00.000Z",
"closedAt": null,
"idempotencyKey": "job-8841",
"metadata": {
"job": "8841"
},
"createdAt": "2026-10-16T10:15:00.000Z",
"updatedAt": "2026-10-16T10:15:00.000Z"
}
],
"has_more": false,
"next_cursor": null
}
Errors
| Code | HTTP status | When | What to do |
|---|---|---|---|
validation_failed | 400 | id isn't a wallet ID, or a filter or pagination value is invalid. | Fix the fields listed in details.issues and send the request again. |
resource_not_found | 404 | This brand has no such wallet in this mode (wallets belong to one brand and one mode). | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
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 read this brand's wallets (wallets:read). | 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, authentication_required, api_key_invalid, dry_run_not_supported, rate_limited, internal_error.