For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Effects

Returned in the response

Applied in the background; read them later or receive them through webhooks

Preview without saving

Yes (dryRun=true)

No

Points per product, product pricing, suggestions, challenge progress

Yes

No

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.

📖 Full schema, parameters and status codes: Register a transaction or custom event and return the applied effects in the API Reference.


🧾 The request

POST /api/{storeCode}/event?dryRun=true&_locale=en
X-AUTH-TOKEN: <api key>
Content-Type: application/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.

  • 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 event's attributes.

  • 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

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.

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) or from webhooks. 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.


⚠️ 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.

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 in the Admin Panel uses its own simulation and doesn't show the Real-Time API's extra sections.

Last updated

Was this helpful?