Fair Usage Policy
Overview
The loyalty API answers live moments: a member is identified at checkout, a basket closes, points pay part of a bill. All integrations share the same capacity, so every integration is expected to call the API when one of those moments happens, and not otherwise.
This page explains what that means in practice, how we react when traffic stops following it, and what your integration should do when we slow it down.
One Real Event, One Call
Each call should be started by something a member or a cashier just did. The table shows the usual pairs.
| What just happened | Call |
|---|---|
| A member signs in or is identified | /member/details |
| A new member joins the program | /member/register |
| A member changes their profile or consents | /member/update |
| A member pays with points or credit | /payment |
| A sale or a return is completed | /transaction |
Read the member once per session or checkout and reuse the answer while that session lasts. Request the balance again only after something has changed it, such as a payment or a completed sale.
Traffic We Treat as Misuse
The following patterns put load on the platform that no member caused. We act on them:
- Polling. Calling
/member/detailson a timer to see whether a balance or a tier has changed. - Walking the member base. Looking up many different members one after another with the same API key, for example to copy them into another system.
- Using live endpoints as a data source. Filling a reporting database, a BI tool or a CRM from the member and transaction endpoints above.
- Retry storms. Sending a failed request again immediately and repeatedly, instead of waiting as described below.
How Limits Are Applied
We do not publish a fixed number of requests per minute or per day. Limits depend on how a key is used: we may review traffic per API key and compare it with that integration's normal pattern. When a key shows one of the patterns above, or a sudden rise that no business activity explains, we can, without notice:
- Lower the request limit of that key.
- Slow down its responses.
- Suspend the key for a period.
A restriction is usually lifted once the traffic is back to its normal pattern. An integration that follows the "one real event, one call" rule is unlikely to meet one.
Handling HTTP 429
When a key goes over its limit, the API answers with HTTP status 429 Too Many Requests (MDN reference). Your integration must handle it:
- Stop sending requests with that key for a moment. Do not resend the failed request at once.
- Wait longer after every failed try (exponential backoff), for example 1, 2, 4, then 8 seconds, and add a small random delay so that many terminals do not retry at the same second.
- Give up after a few tries and report the error, instead of retrying forever.
- Do not retry other
4xxerrors. They mean the request itself is wrong and will fail again.
At checkout, do not let a 429 block the sale. A completed sale can be kept in a queue on your side and sent to /transaction once the wait is over.
Bulk Data and Reporting
Contact us before you build any bulk transfer or historical reporting, and we will agree on a method with you. Do not build it on the live endpoints above.
The usual method is the Sync API, which is meant for reading many records:
/members,/transactions,/paymentsand/assetsreturn records page by page.- Filter by date and read only the records that are new since your last run, instead of reading everything again.
- Request pages one after another, not in parallel.
- Schedule large exports outside the business's busiest hours.
Repeated Misuse
A key that keeps breaking this policy after it was restricted, or that is used to extract data on purpose, can lose its access completely. If one of your keys was restricted and you do not know why, contact us with the integration name and the time it happened.