List a customer's promotional grants and their state-machine state
Lists a customer’s promotional-money grants and the lifecycle state of each. Each grant in the response includes its source (CASHBACK, RELOAD_BONUS, SKU_TOPUP_BONUS, or GATEWAY_BONUS), its state (LOCKED, RELEASED, CLAWED_BACK, or EXPIRED), its original amount, its remaining amount (remaining_minor), and its expiry. All amounts are integer minor units in the grant’s explicit ISO-4217 currency.
Promotional money is a separate value class from the customer’s spendable cash balance: it expires, is never cashable out, and is spent before cash under promo-first ordering. A CASHBACK grant accrues in LOCKED state and does not become available until the customer registers (proves phone ownership) and the merchant’s claim gate is satisfied; only then does it transition to RELEASED. Use this endpoint as the operational view of what bonus value a customer holds and in what state.
This endpoint is read-only and tenant-scoped: it returns only grants belonging to the authenticated tenant. Results are cursor-paginated.
Authorizations
POS terminal JWT minted by /auth/token; carries integrationId + terminal/cashier claims (server-trusted).
Path Parameters
The wallet identity id.
Query Parameters
Filter by grant state.
LOCKED, RELEASED, CLAWED_BACK, EXPIRED Opaque cursor (C7).
Max per page (default 50, max 100).
1 <= x <= 100Response
The customer's promotional grants.
The standard response envelope that every enveloped endpoint serializes through. ok is a boolean discriminator: when ok is true, the typed result is carried in data; when ok is false, a typed error object is returned instead. The meta object is uniform across the entire API surface.
The uniform response metadata block returned on every response. data_completeness_score is computed per call and reports the completeness of the returned data. decision_trace_id is present on responses that carry decision or insight output and can be used to correlate the response with its reasoning. capabilities is an additive, response-level array of hints advertising features the caller may use, and may be extended over time without notice.
Cursor-paginated list of a customer's promotional grants.
The typed error object returned with every non-2xx response. code is a string enum (for example WALLET_PROGRAM_AMBIGUOUS, CREDENTIAL_TYPE_UNSUPPORTED, INSUFFICIENT_FUNDS, IDEMPOTENCY_KEY_REUSED, CURRENCY_NOT_SUPPORTED), never a bare HTTP status number. Inspect code for programmatic branching, not the HTTP status. Some codes echo the valid set in details so clients can present or reconcile the accepted values: for example CREDENTIAL_TYPE_UNSUPPORTED lists the supported credential types, CURRENCY_NOT_SUPPORTED lists the supported ISO-4217 currencies, and WALLET_PROGRAM_AMBIGUOUS lists the candidate wallet_program_id values that matched the request.