Benefits
The commerce's reward catalog, the lookup of a redemption code, and the redemption itself.
This section holds the two halves of a reward's life: the catalog the commerce built, and the redemption of a code a member brings in to use.
A benefit and a redeemable benefit are not the same
The commerce creates benefits, and each one has a benefit_id. When a member
buys one with their points they receive a redeemable benefit with its own
client_benefit_code.
The benefit_id is only good for looking up information. The
client_benefit_code is good for looking up and for redeeming.
The redemption flow
This is what it looks like on your system's side when a member shows up with a code:
The member gives their code
They have it in their Loybox app. It is the client_benefit_code.
You look up what it is
GET /v1/benefits/preview/{client_benefit_code}
tells you which reward it is and, where it applies, what discount to give. It does
not redeem anything yet.
You apply the discount
At your register, your ecommerce or wherever the sale runs, using the previous step's data.
You mark it as used
POST /v1/benefits/redeem. From here on the
code is burned and cannot be used again.
Redeem only once the sale went through
Looking up is harmless and can be repeated; redeeming is final. If you redeem before closing the sale and the sale falls through, the member lost the reward.
The endpoints
List benefits
The full catalog the commerce created.
Get a benefit
One catalog benefit by its benefit_id.
Look up a code
Which reward a client_benefit_code is, before redeeming it.
Look up a code (v2)
The same, with the title and the discount's value at the top level.
Redeem a benefit
Marks the code as used. It is final.
Credential
The whole section goes from your server, with the commerce API key:
Authorization: Bearer {api-key}