List wallets · Ownrecord docs

Lists the brand's wallets in the mode of the request, newest first, with their balances (without the upcoming expiries: get a wallet for those).

customerId: one customer's wallets (one per currency);
currency, status: only wallets in this currency or with this status.

Paginate with limit (1–100, default 10) and starting_after (the next_cursor of the previous page).

At a glance

REST: GET /api/v1/wallets
MCP tool: wallets_list
Operation ID: wallets.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) and starting_after
Authentication: API key with the wallets:read scope
Since: M6

Request

Query parameters

Field	Type	Required	Description
`limit`	integer (1 to 100)	No
`starting_after`	`wal_…` ID	No
`customerId`	`cus_…` ID	No	Only this customer's wallets (spec: `?customer=`).
`currency`	string	No	Only wallets in this currency.
`status`	one of `active`, `frozen`, `closed`	No	Only wallets with this status.

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`	`wal_…` ID
`data[].object`	`"wallet"`
`data[].brandId`	`brd_…` ID
`data[].livemode`	boolean
`data[].customerId`	`cus_…` ID
`data[].currency`	string
`data[].status`	one of `active`, `frozen`, `closed`	`active`, `frozen` (no new reservations or leases) or `closed` (retired; reopened by a purchase).
`data[].statusReason`	string or null	Why the wallet is frozen or closed.
`data[].statusChangedAt`	date-time or null
`data[].available`	money	Spendable purchased, subscription and adjustment credits (not reserved). Expired credits stay here until the hourly expiry job takes them out.
`data[].promo`	money	Spendable promo credits (spent first; never refundable).
`data[].reserved`	money	Held by open reservations and leases.
`data[].balance`	money	All unspent credits: `available + promo + reserved`.
`data[].lowBalanceThreshold`	money or null
`data[].lowBalance`	boolean	The balance is below `lowBalanceThreshold`.
`data[].autoReload`	object or null
`data[].createdAt`	date-time
`data[].updatedAt`	date-time
`has_more`	boolean
`next_cursor`	string or null

Examples

A customer's wallets

HTTP

GET /api/v1/wallets?customerId=cus_01m4ty3c2b5qx7mhd9k8w6s0aa
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "list",
  "data": [
    {
      "id": "wal_01m4ty7w2a5qx7mhd9k8w6s0b1",
      "object": "wallet",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "livemode": false,
      "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0aa",
      "currency": "EUR",
      "status": "active",
      "statusReason": null,
      "statusChangedAt": null,
      "available": {
        "amount": "77000000",
        "currency": "EUR"
      },
      "promo": {
        "amount": "5000000",
        "currency": "EUR"
      },
      "reserved": {
        "amount": "3000000",
        "currency": "EUR"
      },
      "balance": {
        "amount": "85000000",
        "currency": "EUR"
      },
      "lowBalanceThreshold": {
        "amount": "10000000",
        "currency": "EUR"
      },
      "lowBalance": false,
      "autoReload": null,
      "createdAt": "2026-10-14T09:00: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	A filter or pagination value is invalid.	Fix the fields listed in `details.issues` and send the request again.
`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, resource_not_found, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Query parameters#

Response#

Examples#

A customer's wallets#

Errors#