Wallets

A wallet is a per-customer credit balance in a single currency. See Wallets concept.

Object

{
  "id": "wal_…",
  "object": "wallet",
  "customer_id": "cus_…",
  "currency": "USD",
  "balance": "127.50",
  "auto_top_up": {
    "enabled": true,
    "trigger_at": "10.00",
    "amount": "100.00",
    "payment_method_id": "pm_…"
  },
  "drift_floor": "0.00",
  "metadata": {},
  "created_at": "2026-04-01T00:00:00Z",
  "updated_at": "2026-05-06T12:00:00Z"
}

Endpoints

Method	Path	What
POST	/v1/customers/{id}/wallets	Create (one per currency).
GET	/v1/wallets/{id}	Retrieve.
PATCH	/v1/wallets/{id}	Update auto-top-up, drift floor, metadata.
GET	/v1/wallets	List + filter.
POST	/v1/wallets/{id}/credits	Credit (top-up, manual).
POST	/v1/wallets/{id}/debits	Debit (manual; rare).
GET	/v1/wallets/{id}/transactions	Full ledger of credits / debits.

Credit shape

POST /v1/wallets/{id}/credits
{ "amount": "50.00", "reason": "manual_topup", "external_id": "stripe_topup_…" }

reason is required and audited: manual_topup, auto_topup, credit_note, promotional, refund, migration.

external_id deduplicates against your own system.

Settling invoices

Settlement against an open invoice is automatic when the wallet is non-zero in the matching currency. To force wallet-only:

POST /v1/invoices/{id}/pay
{ "source": "wallet" }

Webhook events

wallet.credited, wallet.debited, wallet.auto_topup_succeeded, wallet.auto_topup_failed, wallet.below_drift_floor.