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.
Endpoint
POST /api/{storeCode}/event
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
📖 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—transactionfor 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 ofmemberId,email,phoneorloyaltyCardNumber. A member is required; answers for guest shoppers aren't supported.event.data— for a transaction, theheader(with adocumentNumber), the cartitems, an optionalchannelIdand, optionally,productsToPrice. For a custom event, the event's attributes.responseContent— optional extra response sections, in any combination:unitsPerProduct,suggestions,translations.
Preview or save
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
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, asoperator+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 Acceptedwith the ID of the created transaction or custom event. Its effects are applied in full in the background — read them from the resource in theLocationheader (e.g. Get transaction details) or from webhooks. Don't resend the request.A
202response has noeffectsSummaryor 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-RemainingandX-RateLimit-Reset, so you can see how much headroom is left.A request rejected with
400doesn't count towards the limit.
⚠️ Errors and good to know
The endpoint answers 400 for invalid data and also when:
eventorevent.typeis missing, oreventisn't an object;responseContentcontainsnull, an empty string or an unknown value;the
documentNumberis already used in the tenant — including when a concurrent request with the same number is saved first.
Good to know:
unitsPerProduct,productsToPriceandsuggestionswork for purchase transactions only; on a custom event they're accepted and simply not returned (sendingproductsToPriceon a custom event is a400).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.
effectsSummaryisn't broken down per campaign;unitsPerProductshows 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?

