Prepaid wallets
Prepaid wallets hold customer credits against future usage. Every balance change is an immutable ledger entry; balances are the sum of entries.
For the console and portal walkthrough — creating wallets, top-ups, and alert states — see Wallets (workspace guide).
Concepts
- Top-up — credits added to the wallet (manual or invoice-linked)
- Consumption — credits consumed by usage; blocked when insufficient
- Monthly spend cap — hard limit on month-to-date consumption; a blocked
spend returns
409and leaves no ledger trace - Alert state —
ok/warning(threshold % of cap) /capped/empty
Console
Settings → Billing → Wallets: create wallets per customer with an optional cap, add credits, and monitor alert states at a glance.
Customer portal
Portal → Wallet: balance, month-to-date spend against the cap with a progress bar, alert state, and the recent activity ledger.
API (console session auth)
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/wallets |
List organization wallets with summaries |
| POST | /api/v1/wallets/customers/{id} |
Create/get a wallet (optional controls) |
| POST | /api/v1/wallets/{id}/top-up |
Add credits |
| POST | /api/v1/wallets/{id}/consume |
Consume credits (409 when blocked) |
| PATCH | /api/v1/wallets/{id}/controls |
Set cap / alert threshold |
| GET | /api/v1/wallets/{id}/entries |
Ledger entries |
All endpoints require the wallets:write (mutations) or wallets:read
permission — see Team roles.