Get a customer's loyalty state

View as Markdown

Returns the customer’s current loyalty snapshot — cashback balance, stamps, banked rewards, visits. Customers with no transactions yet return a zeroed snapshot (this endpoint never 404s for emptiness — only for an unknown or cross-tenant customer id). Read it before redeeming to check availableRewards, or after a write to show the updated balance.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

customerIdstringRequired

Perkss customer id (UUID) — the id returned by customer create/list.

Response

The current snapshot; zeroed for customers without transactions.

balanceCentsdouble
Current redeemable cashback balance, in cents. 0 on stamps programs.
totalSpentCentsdouble
Lifetime recorded spend, in cents.
redeemedCentsdouble
Lifetime cashback redeemed, in cents.
stampsCurrentdouble

Stamps collected toward the current card — always below the program’s stamp goal (a completed card banks a reward instead).

availableRewardsdouble
Banked rewards ready to redeem.
visitsdouble
Recorded visit count.
lastTxAtstring or null

ISO 8601 timestamp of the latest transaction; null when the customer has none yet.

Errors

401
Unauthorized Error
404
Not Found Error
429
Too Many Requests Error
503
Service Unavailable Error