Getting started

Record the purchase

At an online checkout you already have the email, so by email is the short path: it works even if the member does not have a Loybox account yet.

curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/consumptions/email \
  -H "Authorization: Bearer $LOYBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_email": "ana@example.com",
    "amount": 1750
  }'

At a physical point of sale, where the member gives their number, it is the same call by code with client_code.

How many points it earns is not decided by your call: it is decided by the commerce's configuration. You send the amount and Loybox applies the money-per-point rule, double points if they are running, and the tier bonus, in that order (the formula).

Show them the balance

The consumption's response does not say how many points it added. The balance is looked up separately:

curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/clients/12345 \
  -H "Authorization: Bearer $LOYBOX_API_KEY"

With this you already have a working program: purchases earn and the member has a balance.

Look up the code the member brings

When a member shows up with a redemption code (their client_benefit_code), the first thing is to see what it is. Use v2, which brings the discount's value at the root:

curl https://loybox-public-api-752998171300.southamerica-west1.run.app/v2/benefits/preview/887766 \
  -H "Authorization: Bearer $LOYBOX_API_KEY"

With the response's type and value you apply the discount in your sale:

A 400 here means the code was already used: do not apply anything.

Redeem it once the sale closed

Redemption burns the code and there is no going back:

curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/benefits/redeem \
  -H "Authorization: Bearer $LOYBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_benefit_code": 887766
  }'

Ask for the code

curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/auth/otp/request \
  -H "X-Commerce-Id: 87" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana@example.com"
  }'

It always answers 200, even if that email has no account. In the UI you always show the same message ("we sent a code to your email"), because you cannot know whether the account existed.

Verify it and store the session

curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/auth/otp/verify \
  -H "X-Commerce-Id: 87" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana@example.com",
    "otp": "418302"
  }'

It returns access and refresh. Store both: the access expires in expires_in seconds and the refresh is what renews it without asking the user for another code. If the email had no account, one is created, and either way the user ends up subscribed to your program.

Paint the screen with a single call

GET /v1/me brings the points, the commerce's branding and the points about to expire, all at once:

const res = await fetch(
  'https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me',
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'X-Commerce-Id': '87',
    },
  },
);

const me = await res.json();
// me.points -> the big balance on the screen
// me.commerce -> logo, name and color for the program's branding
// me.subscribed -> if it comes back false, show the call to join

A 401 here means the access expired: renew it and retry the call.

Show the catalog and buy

The catalog comes back unfiltered by balance: you compare each benefit's cost with the user's points and decide what to show as reachable and what as "you need N more points".

curl -X POST https://loybox-public-api-752998171300.southamerica-west1.run.app/v1/me/benefits/exchange \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Commerce-Id: 87" \
  -H "Idempotency-Key: 8f14e45f-ea0f-4d1c-9a1b-2c3d4e5f6a7b" \
  -H "Content-Type: application/json" \
  -d '{
    "benefit_id": "b_9f2a"
  }'

Show them the code

The purchase returns a client_benefit_code. That number is both the redemption code and the coupon code: in an online store it is what the user pastes at checkout, and in a physical store it is what they show at the counter.

Show it large, with a copy button and the due_date next to it. The full list of the ones they hold is in my benefits.