> 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/technical-guide/integration/real-time-api.md).

# Real-Time API

Register a purchase or custom event and get the applied loyalty effects back in the same response — or preview them without saving — with POST /event.

The Real-Time API registers a purchase transaction or a custom event and returns, **in the same response**, what the campaign engine applied: points, rewards, badges, custom attributes and tiers. It can also preview a request without saving anything, price a list of products against the current cart, tell the member what they're missing for the next reward, and report challenge progress.

Use it wherever a member should see the result at once — a product listing, the cart, the thank-you page, or an in-app action.

|                                                                      | Real-Time API                              | Asynchronous endpoints                                                                                                                                                                                                            |
| -------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Endpoint                                                             | `POST /api/{storeCode}/event`              | [`POST /api/{storeCode}/transaction`](https://help.openloyalty.io/api-reference/transactions/add-a-transaction), [`POST /api/{storeCode}/customEvent`](https://help.openloyalty.io/api-reference/custom-event/add-a-custom-event) |
| Effects                                                              | Returned in the response                   | Applied in the background; read them later or receive them through [webhooks](https://help.openloyalty.io/technical-guide/webhooks/overview.md)                                                                                   |
| `CampaignEffectWasApplied` webhook                                   | Not sent — the effects are in the response | Sent                                                                                                                                                                                                                              |
| Preview without saving                                               | Yes (`dryRun=true`)                        | No                                                                                                                                                                                                                                |
| Points per product, product pricing, suggestions, challenge progress | Yes                                        | No                                                                                                                                                                                                                                |

{% hint style="info" %}
Your existing integration keeps working unchanged. The Real-Time API has a different request and response structure, so moving to it is new integration work rather than a change of URL — and you can adopt it one flow at a time.
{% endhint %}

📖 Full schema, parameters and status codes: [**Register a transaction or custom event and return the applied effects**](https://help.openloyalty.io/api-reference/events/register-a-transaction-or-custom-event-and-return-the-applied-effects) in the API Reference.

***

## 🧾 The request

```http
POST /api/{storeCode}/event?dryRun=true&_locale=en
X-AUTH-TOKEN: <api key>
Content-Type: application/json
```

```json
{
  "event": {
    "type": "transaction",
    "memberData": { "email": "member_1@example.com" },
    "data": {
      "header": { "documentNumber": "DOC12346789", "purchasedAt": "2026-01-13 11:40:35+01:00" },
      "items": [
        { "sku": "PROD1", "name": "T-Shirt", "highPrecisionQuantity": 1, "grossValue": 200, "category": "T-Shirt" }
      ],
      "productsToPrice": [
        { "sku": "PROD2", "name": "Cap", "highPrecisionQuantity": 1, "grossValue": 40, "category": "Accessories" }
      ]
    }
  },
  "responseContent": ["unitsPerProduct", "suggestions", "translations"]
}
```

* **`event.type`** — `transaction` for a purchase transaction. Any other value is a custom event type and must match an active [custom event schema](https://help.openloyalty.io/technical-guide/getting-started-guide/add-custom-event-schema.md).
* **`event.memberData`** — identifies the member by one of `memberId`, `email`, `phone` or `loyaltyCardNumber`. A member is required; answers for guest shoppers aren't supported.
* **`event.data`** — for a transaction, the `header` (with a `documentNumber`), the cart `items`, an optional `channelId` and, optionally, `productsToPrice`. For a custom event, the `eventDate`, an optional `eventId` (see *Retries and duplicates* below) and the event's attributes in `body`.
* **`responseContent`** — optional extra response sections, in any combination: `unitsPerProduct`, `suggestions`, `translations`.

### Preview or save

| Mode               | How           | What happens                                                                                                                       |
| ------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Save** (default) | no `dryRun`   | The event is created and its effects are applied — points, rewards and challenge progress are granted at once.                     |
| **Preview**        | `dryRun=true` | Nothing is saved. The response has the same shape and the same values the request would grant for real, for the same member state. |

The `documentNumber` is required in both modes. In a preview nothing is stored, so a product listing or cart can send the same placeholder each time; when saving, it must be unique in the tenant, as for any transaction.

***

## 📦 The response

```json
{
  "event": { "eventId": "…", "matched": true, "member": { "email": "member_1@example.com", "memberId": "…" }, "createdAt": "2026-01-13T11:40:35+01:00" },
  "effectsSummary": { "givenUnits": [{ "walletCode": "default", "units": 30 }] },
  "unitsPerProduct": [
    { "campaignId": "0f3c…", "walletCode": "default", "units": 30,
      "lines": [{ "lineIndex": 0, "sku": "PROD1", "units": 30 }] }
  ],
  "productsToPrice": [{ "sku": "PROD2", "earned": { "givenUnits": [{ "walletCode": "default", "units": 15 }] } }],
  "suggestions": [
    { "campaignId": "0f3c…",
      "missing": [{ "type": "transactionAmount", "required": 500, "current": 420, "operator": "gte" }],
      "wouldEarn": [{ "type": "points", "walletCode": "default", "value": 100 }] }
  ],
  "translations": { "campaigns": { "0f3c…": { "name": "Double points weekend" } }, "walletTypes": { "default": { "name": "Points" } } }
}
```

| Section             | When it's there                                                    | What it tells you                                                                                                                                                         |
| ------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `effectsSummary`    | Whenever an effect was applied                                     | Units given and deducted, rewards, badges, custom attributes assigned or removed, tiers assigned. Only effects that were actually applied — not ones rejected by a limit. |
| `challengeProgress` | Automatically, when the event moved one of the member's challenges | Progress before and after, per milestone, and whether the challenge was completed.                                                                                        |
| `unitsPerProduct`   | Requested, purchase transactions only                              | How the units the cart earned split across its lines. The lines add up to the total.                                                                                      |
| `productsToPrice`   | When the request has `productsToPrice`                             | One quote per candidate product, in request order.                                                                                                                        |
| `suggestions`       | Requested, purchase transactions only                              | Campaign rules the cart didn't meet, with what's missing and what closing the gap would earn.                                                                             |
| `translations`      | Requested                                                          | Names and descriptions for the IDs and codes in the response, in the `_locale` language.                                                                                  |

A section with nothing to report is left out entirely — never `null` or empty.

{% hint style="warning" %}
**No `CampaignEffectWasApplied` webhook.** For an event registered through the Real-Time API, the campaign effects come back only in this response: the [`CampaignEffectWasApplied`](https://help.openloyalty.io/integrations-and-data-exchange/webhooks/what-triggers-a-webhook) webhook isn't sent, whatever the effect type. If a downstream system (for example, a CRM sending "you earned…" messages) relies on that webhook, pass it the effects from the response instead. This applies to events answered with `200`; for a `202`, see *Traffic peaks and rate limit* below.
{% endhint %}

### Points per line (`unitsPerProduct`)

Shows which product earned which points, e.g. *earbuds +278, cable +10* — on the receipt, in the order confirmation or for support. The split exists for points from campaigns whose effects are bound to a product target (the **Number**, **Quantity** or **Value of items in target** conditions); campaigns that reward the transaction as a whole count at the cart level only.

### Products to price (`productsToPrice`)

Prices product listings, product pages and menus in one call. Each candidate is valued separately as **current cart + this one product**, never together with the other candidates — so:

* the values **don't add up** to a basket total, and the cart changes the result (a product can take the basket over a spend threshold);
* a value can be **negative** if adding the product would break a promotion the cart already has;
* an empty cart is allowed in a preview — the value is then "this product alone".

The list size is capped per environment; a longer list is rejected with `400`, not truncated. Suggestions aren't calculated for candidates — only for the actual cart. When saving, the transaction is registered as usual and the quotes are priced against the member as they were before this purchase.

### Suggestions (`suggestions`)

Every campaign rule the cart didn't meet, each with:

* **`missing`** — what's missing, as `operator` + `required` (+ `current`): a spend amount, a quantity, a number of lines, a specific product, category, brand, collection, product-catalog category, brand or attribute, a bundle, or a member condition (wallet balance, badge, tier, segment, label, profile attribute). Your integration works out "how many more" — only it knows the unit (pieces, kilograms…).
* **`wouldEarn`** — what closing the gap would add: points, a reward, a badge, a tier or a custom attribute.

Suggestions go through the same engine that grants the rewards, so eligibility, campaign and wallet limits and reward stock are respected — a member is never promised a reward they can't get. A suggestion whose value can't be calculated exactly is left out, and rules whose conditions can't be turned into an action (custom formulas, exclusions, purchase place, referrer conditions) are skipped. Each suggestion is calculated on its own against the cart as sent — closing every gap at once isn't guaranteed to unlock every reward. Your store decides which suggestions to show, where and in what order.

### Translations (`translations`)

The response always identifies campaigns, rewards, wallets, badges, tiers and milestones by ID or code. With `translations`, it also returns their names (and, for rewards, descriptions, conditions and brand details) in the `_locale` language. An unknown locale falls back to its parent language (`pl_PL` → `pl`), then to the tenant's default language — never an error.

***

## 🚦 Traffic peaks and rate limit

The Real-Time API is built so that a traffic peak never loses an event:

* **Previews are never limited**, so product pages and carts always get an instant answer.
* **Writes above the limit aren't rejected.** If more writes arrive than your environment processes synchronously, the event is still registered and the API answers **`202 Accepted`** with the ID of the created transaction or custom event. Its effects are applied in full in the background — read them from the resource in the `Location` header (e.g. [Get transaction details](https://help.openloyalty.io/api-reference/transactions/get-transactions-details)) or from [webhooks](https://help.openloyalty.io/technical-guide/webhooks/overview.md). **Don't resend the request.**
* A `202` response has no `effectsSummary` or other sections, so show a neutral message ("points are on their way") rather than a number.
* Every write response carries **`X-RateLimit-Limit`**, **`X-RateLimit-Remaining`** and **`X-RateLimit-Reset`**, so you can see how much headroom is left.
* A request rejected with `400` doesn't count towards the limit.

***

## 🔁 Retries and duplicates

A saved event can't be taken back, so make every write safe to send again:

* **Transactions** — the `documentNumber` must be unique in the tenant, so a resent transaction is rejected with `400` instead of being registered twice.
* **Custom events** — send a stable `data.eventId` (up to 255 characters), such as your own ID for the action. A custom event whose `eventId` is already used in the tenant is rejected with `400`, so a retry can't apply its effects again. The check covers all custom event types, so keep the ID unique across types, not only within one.
* **Without an `eventId`**, a resent custom event is registered again and its points, rewards and other effects are applied a second time. Always send one.

### Concurrent requests for the same member

Writes for the same member are processed one at a time: a second request waits until the first one has finished. If it can't start within the lock timeout (5 seconds by default), the API answers `503`. Send the request again with the same `documentNumber` or `eventId` — the duplicate checks above make that safe. Previews aren't affected.

***

## ⚠️ Errors and good to know

The endpoint answers `400` for invalid data and also when:

* `event` or `event.type` is missing, or `event` isn't an object;
* `responseContent` contains `null`, an empty string or an unknown value;
* the `documentNumber` is already used in the tenant — including when a concurrent request with the same number is saved first;
* the custom event's `data.eventId` is already used in the tenant.

It answers `503` when another request for the same member kept it waiting too long — see [Concurrent requests for the same member](#concurrent-requests-for-the-same-member).

Good to know:

* `unitsPerProduct`, `productsToPrice` and `suggestions` work for purchase transactions only; on a custom event they're accepted and simply not returned (sending `productsToPrice` on a custom event is a `400`).
* Per-rule product limits aren't yet reflected in suggested values — a member may receive less than a suggestion shows when a rule has its own limit.
* `effectsSummary` isn't broken down per campaign; `unitsPerProduct` shows which products earned the points, not which campaign.
* Challenge progress covers challenges the member takes part in; legacy achievements that haven't been migrated to challenges aren't included.
* The [campaign simulator](https://help.openloyalty.io/campaigns/campaigns/campaign-simulation) in the Admin Panel uses its own simulation and doesn't show the Real-Time API's extra sections.


---

# 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/technical-guide/integration/real-time-api.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.
