My account
The end user's endpoints: their points, their benefits, their history and their tier in your program.
Endpoints for the end user, authenticated with the access token returned by verifying the code:
Authorization: Bearer {access}
X-Commerce-Id: {your-commerce-id}Everything they return is scoped to the commerce in the X-Commerce-Id header:
points, benefits, history and tier belong to that program and nothing else. The
same user can be in several Loybox programs, and each one only sees its own.
The typical circuit
This is how a loyalty website is built with these endpoints:
The first render
GET /v1/me brings the points, the commerce's
branding and the points about to expire, all at once. With a single call you paint
the header and the balance.
The catalog
GET /v1/me/benefits/available
to show what they can redeem.
The purchase
POST /v1/me/benefits/exchange
trades points for a benefit.
The codes
GET /v1/me/benefits to show them the
codes they hold to present at the commerce.
When building the UI
Three things that save round trips:
- Each of the user's benefit
client_benefit_codeis also the coupon code: in an online store it is what the user pastes at checkout. - Benefits carry
benefit_type, which separates catalog ones (normal) from the special rewards (welcome,birthday,monthly_top,level), andcolor, the commerce's brand color. - How much the user is short for a benefit is the benefit's
costminus thepointsfromGET /v1/me.
Buying and redeeming are not the same
| Buying | Redeeming | |
|---|---|---|
| What it does | Trades points for a benefit | Uses the benefit at the commerce |
| Who calls it | The user, from your website | Your server, at the sale |
| Endpoint | POST /v1/me/benefits/exchange | POST /v1/benefits/redeem |
| Credential | End-user token | Commerce API key |
The endpoints
My account
Points, commerce branding and points about to expire, in one call.
Benefits I can buy
The commerce's live catalog.
Buy a benefit
Trades points for a benefit. Accepts Idempotency-Key.
My benefits
The ones already bought, with their redemption code.
My history
Consumptions, purchases, redemptions and rewards. Cursor paginated.
My tier
Current tier, multiplier and progress to the next one.
Program rewards
Welcome, birthday and member of the month.
Join the program
Joining the club. Returns the welcome reward.
Opt out
Leaving the club without losing the points.
The 401 across the whole section
All of these endpoints return 401 when the access token is missing, expired, or
does not belong to an end user. It is the normal case once time has passed:
renew it and retry the call.