Overview

Use wallets to manage the money customers can spend in your store. All money fields use integer minor units: 1250 means $12.50 for a USD wallet. Floating-point amounts are never accepted.

Abilities

• wallet can read settings and customer balances.
• wallet:write can read and perform sensitive mutations, including manual adjustments, freezes, settings changes, cashback rules, and bonus tiers.

Dashboard wallet permission is also required. A customer or product ID from another store returns 404 or a validation error without exposing foreign data.

Customer-funded top-ups

Create a wallet top-up payment link when the customer should pay to add funds. It requires both wallet and charge permissions. Share the returned checkout URL; creating the link does not credit the wallet. Use a manual adjustment only when you intend to change the balance directly without collecting payment.

Accounting boundary

Each manual adjustment saves a permanent MANUAL_ADJUSTMENT transaction record and updates the balance together. Send a stable idempotency_key for every adjustment. Retrying identical input returns the original entry; reusing the key for different input is rejected.

Wallet ledger entries are separate from credits and rewards. This API does not grant credit packages or create reward grants.

Incentive rules

Cashback percentages and percentage bonus tiers use basis points, where 750 means 7.50%. Editing a bonus tier archives the old record and creates a replacement so historical ledger attribution remains intact.