Skip to main content
POST
Preview Event Rewards
Returns the points and coupon rewards a customer would earn if the given event(s) fired now. Use this for custom events (the same events you send to Send Events). For orders, use Preview Order Rewards instead. This endpoint is a read-only quote:
  • No points are awarded and no coupons are generated.
  • Nothing appears in the customer’s activity or history.
  • Campaign budgets and frequency limits are not consumed.
  • Calling a preview any number of times has no side effects.
The calculation applies the same logic as a live event: active reward campaigns, metadata conditions, dynamic reward multipliers, and per-customer frequency limits — so the previewed value matches what a real submission would award at that moment.
Security: Provide apikey header. secretkey is required on v4.1; on v4.0 required when High Security Mode is enabled.
Unlike Send Events, the preview never creates the customer. Unknown or inactive customers return an error.

Localization

Send the optional lang header (for example ar, en, fr) to localize campaigns[].campaignName. If you omit the header, or send a code that is not configured in your account, the response falls back to your account’s default language. No error is returned. These fields are stable machine-readable values — map them to your own translated copy instead of displaying them directly:

reason values

Campaigns the customer can no longer win are omitted. If the customer already used up a campaign’s per-customer limit, or is outside the campaign’s audience or activation criteria, that campaign does not appear in campaigns — matching exactly what the live engine would (not) award. Inactive or expired campaigns are also never returned.

Notes and limitations

  • Previews are point-in-time quotes. A concurrent real event for the same customer can change eligibility between the preview and the actual submission.
  • Campaign budgets are not checked. A campaign whose budget is exhausted may preview rewards that a real submission would reject.
  • Coupons are described, never created. couponType / couponValue tell you what the customer would get; actual coupon codes are generated only by real events.
  • Unknown metadata keys are ignored by previews (they are not registered as new keys, unlike live events).
  • Streak badges and mission step rewards are not included in preview results.
Also see Preview Order Rewards for cart and checkout messaging.

Authorizations

apikey
string
header
required

Headers

lang
string

Language code for localized campaign names in campaigns[] (e.g., en, ar, fr). If omitted or not configured in your account, the response falls back to your account's default language.

Body

application/json
customerId
string
required

The customer's unique ID in your system. Must be an existing, active customer.

Maximum string length: 100
Example:

"1214"

events
object
required

One entry per event to preview: the key is the event name, the value is that event's metadata object (or {} / null if none).

Example:
email
string

Used only to help locate the customer (channel merge).

mobile
string

Used only to help locate the customer (channel merge).

Response

Event reward preview calculated successfully

customerId
string

Echo of the request.

totalPoints
integer

Sum of points across all previewed events.

events
object[]

One independent result per event sent, in request order.