Overview
Manage store wallet settings, customer balances, cashback rules, and top-up bonus tiers.
The wallet API exposes store-scoped administrative controls. All money fields use integer minor units: 1250 means $12.50 for a USD wallet. Floating-point amounts are never accepted.
Abilities
walletcan read settings and customer balances.wallet:writecan 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.
Accounting boundary
Manual adjustments append immutable MANUAL_ADJUSTMENT ledger entries and atomically update the cached balance. Send a stable idempotency_key for every adjustment. Replaying 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.