> For the complete documentation index, see [llms.txt](https://help.openloyalty.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.openloyalty.io/implementation-guide/reference/api-best-practices.md).

# API Best Practices

Practical rules for integrating with the Open Loyalty API — identifiers, updates, idempotency, querying, retries and caching — collected from real implementations.

The Developer Guide covers the API fundamentals: [best practices](https://help.openloyalty.io/technical-guide/api-fundamentals/best-practices), [how to query](https://help.openloyalty.io/technical-guide/api-fundamentals/how-to-query), [limits](https://help.openloyalty.io/technical-guide/api-fundamentals/limits) and [environments](https://help.openloyalty.io/technical-guide/api-fundamentals/environments-capabilities). This page collects the rules that matter most in an implementation, with links to the pages of this guide that explain them.

## Requests

* Send every request with an `X-AUTH-TOKEN` API key and a `User-Agent` header — requests without a `User-Agent` are blocked.
* The API times out after **60 seconds**; long-running work belongs in imports and exports, not single calls.
* Keep each integration on its own API key — see [Environments & access](https://help.openloyalty.io/implementation-guide/plan-and-foundations/environments-and-access.md).

## Identifiers

* Address members as `identifier=value` in the path, e.g. `/member/loyaltyCardNumber=100234567/wallet`. A bare value returns `404`.
* A few calls need the `customerId` UUID — for example `POST /reward/{reward}/buy`. Read it once and cache it with the member.
* See [Member identity](https://help.openloyalty.io/implementation-guide/plan-and-foundations/member-identity.md).

## Updates

* `PUT` replaces the whole object. Always **GET → merge → PUT**; a PUT built from partial data wipes labels and custom fields.
* For a member's labels and custom fields only, use `PATCH`.
* For rewards and campaigns, remove read-only fields from the GET response before the PUT.

## Idempotency

Make every write that can be retried safe to repeat. Open Loyalty rejects duplicates of these, which turns a retry into a no-op:

| Write        | Unique field                                     | On a repeat                                                       |
| ------------ | ------------------------------------------------ | ----------------------------------------------------------------- |
| Transaction  | `header.documentNumber`                          | `400` "document number should be unique"                          |
| Custom event | `eventId`                                        | `400` "Custom Event with such event id already exists"            |
| Adding units | `externalTransferId`                             | `400` "Unit transfer with such externalTransferId already exists" |
| Member       | the unique identifier (e.g. `loyaltyCardNumber`) | `409`                                                             |

Build these IDs from the source (order number, `{customer}_{action}`, `MIG-{id}-{wallet}`), never randomly per attempt, and treat the repeat response as success. Fortune wheel draws are different: retry the **same** `issuedRewardId`, never buy a new spin.

## Querying lists

* Always send `_page`, `_itemsOnPage` and `_orderBy` — don't rely on defaults.
* `_itemsOnPage` is at most **50**; `_page` is at most **500** on large lists. Beyond that, use the [scroll mechanism](https://help.openloyalty.io/technical-guide/api-fundamentals/scroll-mechanism-for-pages) or a data export.
* Filters on different fields combine with AND; several **label** filters in one query combine with **OR** — see [Multi-brand programmes and wallets](https://help.openloyalty.io/implementation-guide/plan-and-foundations/multi-brand-and-wallets.md).
* Type filters use the comma form: `type[in]=PointsWereAdded,PointsWereSpent`.
* URL-encode `+` in timezone offsets (`%2B02:00`).

## Errors and retries

| Response               | What to do                                                                                                       |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `400`                  | Don't retry (except to recognise a duplicate — see above). Read the field errors, log the payload, fix the data. |
| `401`, `403`           | Check the API key and the admin's role. Don't retry blindly.                                                     |
| `404`                  | Check the identifier form (`loyaltyCardNumber=…`) and that the member exists.                                    |
| `409`                  | Usually "already exists" or "already used" — treat according to the call.                                        |
| `429`, `5xx`, timeouts | Retry with exponential backoff and jitter; alert after repeated failures.                                        |

Log every failed request with its payload so it can be replayed.

## Caching

* Cache what rarely changes: wallet codes, reward categories, badge types, tier sets, the list of active campaigns and leaderboards. Refresh on a schedule or on the `CampaignUpdated` / `RewardUpdated` webhooks.
* Don't cache what members expect to be current: balances, coupon status, mission progress.
* Look up IDs by code or name per environment — IDs differ between staging and production.

## Checklist

* [ ] Every request carries an API key and a `User-Agent`.
* [ ] Members are addressed as `identifier=value`; `customerId` is cached where needed.
* [ ] Every PUT is preceded by a GET and a merge.
* [ ] Every retryable write has a deterministic unique ID, and duplicate responses are treated as success.
* [ ] List calls set paging and ordering, and deep lists use scroll or exports.
* [ ] Retries back off on `429`/`5xx` and never on `400`.
* [ ] Caches hold only slow-changing configuration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.openloyalty.io/implementation-guide/reference/api-best-practices.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
