Skip to main content
GET
List a customer's promotional grants and their state-machine state

Authorizations

Authorization
string
header
required

POS terminal JWT minted by /auth/token; carries integrationId + terminal/cashier claims (server-trusted).

Path Parameters

customerId
string<uuid>
required

The wallet identity id.

Query Parameters

state
enum<string>

Filter by grant state.

Available options:
LOCKED,
RELEASED,
CLAWED_BACK,
EXPIRED
cursor
string

Opaque cursor (C7).

limit
integer
default:50

Max per page (default 50, max 100).

Required range: 1 <= x <= 100

Response

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.

ok
boolean
required
meta
object
required

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.

data
object

Cursor-paginated list of a customer's promotional grants.

error
object | null

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.