Open a customer's wallet · Ownrecord docs

Returns the customer's wallet in a currency, opening it when it doesn't exist yet: a customer has one wallet per currency in each brand and mode (spec §17.1). Top-ups, credit packs and subscription credits open the wallet themselves; open it here to grant credits (credit_grants.create) before the customer has bought any.

Calling it again returns the same wallet, whatever its status.

At a glance

REST: POST /api/v1/wallets
MCP tool: wallets_create
Operation ID: wallets.create
Scope: Brand
Permission: wallets:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Plan feature: usage_billing.enabled
Authentication: API key with the wallets:write scope
Since: M6

Request

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`customerId`	`cus_…` ID	Yes	The customer (`cus_…`) of the brand.
`currency`	string	Yes	The wallet's currency (one wallet per customer and currency).

Response

201 Created 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

Open a customer's EUR wallet

HTTP

POST /api/v1/wallets
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0aa",
  "currency": "EUR"
}

Response (201):

JSON

{
  "id": "wal_01m4ty7w2a5qx7mhd9k8w6s0b1",
  "object": "wallet",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0aa",
  "currency": "EUR",
  "status": "active",
  "statusReason": null,
  "statusChangedAt": null,
  "available": {
    "amount": "0",
    "currency": "EUR"
  },
  "promo": {
    "amount": "0",
    "currency": "EUR"
  },
  "reserved": {
    "amount": "0",
    "currency": "EUR"
  },
  "balance": {
    "amount": "0",
    "currency": "EUR"
  },
  "lowBalanceThreshold": null,
  "lowBalance": false,
  "autoReload": null,
  "createdAt": "2026-10-14T09:00:00.000Z",
  "updatedAt": "2026-10-16T10:15:00.000Z",
  "upcomingExpiries": []
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`customerId` or `currency` is missing or malformed.	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	This brand has no such customer in this mode.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`customer_deleted`	400	The customer was deleted.	Create a new customer for this buyer. Deleted customers stay readable for the records they belong to, but can't be changed.
`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.
`entitlement_required`	403	The organization's plan doesn't include usage billing (`usage_billing.enabled`).	Upgrade the organization's plan, or remove something to get back under the limit.

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#

Body#

Response#

Examples#

Open a customer's EUR wallet#

Errors#