Get a wallet and its balance
The wallets.get operation: GET /api/v1/wallets/{id} in the REST API and the wallets_get tool in the MCP server.
GET
/api/v1/wallets/{id}Returns a wallet with its balances, its settings and the next credits to expire (spec §17.1):
available: spendable purchased, subscription and adjustment credits;promo: spendable promo credits (spent first);reserved: held by open reservations and leases;balance: all three together;upcomingExpiries: the next grants to expire, soonest first, with what is left of each;lowBalanceThresholdandlowBalance, the auto-reload settings (autoReload) and the status.
Amounts are integer micros in the wallet's currency.
At a glance
- REST:
GET /api/v1/wallets/{id} - MCP tool:
wallets_get - Operation ID:
wallets.get - Scope: Brand
- Permission:
wallets:read - Risk tier:
read - Dry run: Not supported
- Idempotency: Not needed (read only)
- Modes: Test and live
- Authentication: API key with the
wallets:readscope - Since: M6
Request
Path parameters
| Field | Type | Description |
|---|---|---|
id | wal_… ID | The wallet (wal_…). |
Query parameters
This operation takes no query parameters.
Response
200 OK with a JSON object:
| Field | Type | Description |
|---|---|---|
id | wal_… ID | |
object | "wallet" | |
brandId | brd_… ID | |
livemode | boolean | |
customerId | cus_… ID | |
currency | string | |
status | one of active, frozen, closed | active, frozen (no new reservations or leases) or closed (retired; reopened by a purchase). |
statusReason | string or null | Why the wallet is frozen or closed. |
statusChangedAt | date-time or null | |
available | money | Spendable purchased, subscription and adjustment credits (not reserved). Expired credits stay here until the hourly expiry job takes them out. |
promo | money | Spendable promo credits (spent first; never refundable). |
reserved | money | Held by open reservations and leases. |
balance | money | All unspent credits: available + promo + reserved. |
lowBalanceThreshold | money or null | |
lowBalance | boolean | The balance is below lowBalanceThreshold. |
autoReload | object or null | |
upcomingExpiries | array of object | The next grants to expire (at most 10), soonest first. |
upcomingExpiries[].grantId | grant_… ID | |
upcomingExpiries[].source | one of purchase, subscription, promo, adjustment, refund_reversal | |
upcomingExpiries[].remaining | money | What is left of the grant; whatever is unused at expiresAt expires. |
upcomingExpiries[].expiresAt | date-time | |
createdAt | date-time | |
updatedAt | date-time |
Examples
A wallet with promo credits expiring next month
HTTP
GET /api/v1/wallets/wal_01m4ty7w2a5qx7mhd9k8w6s0b1
Authorization: Bearer or_test_…
Response (200):
JSON
{
"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",
"upcomingExpiries": [
{
"grantId": "grant_01m4ty7w2a5qx7mhd9k8w6s0b3",
"source": "promo",
"remaining": {
"amount": "5000000",
"currency": "EUR"
},
"expiresAt": "2026-11-01T00:00:00.000Z"
}
]
}
A wallet with auto-reload
HTTP
GET /api/v1/wallets/wal_01m4ty7w2a5qx7mhd9k8w6s0b1
Authorization: Bearer or_test_…
Response (200):
JSON
{
"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": {
"enabled": true,
"below": {
"amount": "10000000",
"currency": "EUR"
},
"amount": {
"amount": "50000000",
"currency": "EUR"
},
"paymentMethodId": "pm_01m4ty7w2a5qx7mhd9k8w6s0b6",
"failureCount": 0,
"pendingSince": null,
"lastFailureAt": null,
"disabledAt": null
},
"createdAt": "2026-10-14T09:00:00.000Z",
"updatedAt": "2026-10-16T10:15:00.000Z",
"upcomingExpiries": [
{
"grantId": "grant_01m4ty7w2a5qx7mhd9k8w6s0b3",
"source": "promo",
"remaining": {
"amount": "5000000",
"currency": "EUR"
},
"expiresAt": "2026-11-01T00:00:00.000Z"
}
]
}
Errors
| Code | HTTP status | When | What to do |
|---|---|---|---|
validation_failed | 400 | id isn't a wallet ID (wal_…). | 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.