> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Preview Event Rewards
> Quote points and coupon rewards a customer would earn from custom events before anything is awarded.
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](/api-reference/events/send-events)). For orders, use [Preview Order Rewards](/api-reference/order/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](/api-reference/events/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:
| Field | Notes |
| ------------------------------------ | --------------------------------------------------------------------------------- |
| `reason` | Fixed enum: `Rewarded`, `ProgressOnly`, `NoMatchingConditions`, `NonPointsReward` |
| `rewardType`, `completionRewardType` | `Points` / `Coupon` |
| `couponType` | Coupon-kind identifier (e.g. `Percentage`, `FreeShipping`) |
| `invalidReason` | Diagnostic code (`EventNotFound`, `InvalidMetadata: ...`, `PreviewFailed`) |
| `eventName` | Echoed back exactly as you sent it |
### `reason` values
| Reason | Meaning | `points` |
| ---------------------- | ------------------------------------------------------------------------------------------------------- | -------- |
| `Rewarded` | The event would achieve the campaign now; points returned | > 0 |
| `NonPointsReward` | The event would achieve the campaign now, but the reward is a coupon — see `couponType` / `couponValue` | 0 |
| `ProgressOnly` | The event advances the campaign without completing it — see `progress` | 0 |
| `NoMatchingConditions` | The campaign listens to this event, but the metadata you sent did not satisfy its conditions | 0 |
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](/api-reference/order/preview-order-rewards) for cart and checkout messaging.
## OpenAPI
````yaml POST /api/v4.0/integrations/events/reward-preview
openapi: 3.1.0
info:
title: Gameball API
description: >-
Gameball REST API v4.0 - Complete API reference for integrating loyalty,
gamification, and customer engagement features
version: 4.0.0
servers:
- url: https://api.gameball.co
security:
- bearerAuth: []
paths:
/api/v4.0/integrations/events/reward-preview:
post:
tags:
- Events
summary: Preview Event Rewards
description: >-
Returns the points and coupon rewards a customer would earn if the given
event(s) fired now. Intended for custom events (the same events you send
to Send Events). For orders, use Preview Order Rewards instead.
This is a read-only quote — no points are awarded, no coupons are
generated, nothing appears in the customer activity history, and
campaign budgets or frequency limits are not consumed.
Unlike the live events endpoint, the preview never creates the customer
— unknown or inactive customers return an error.
**Security:** Requires `apiKey` header. `secretKey` is required on v4.1;
on v4.0 required when High Security Mode is enabled.
**Localization:** Send the optional `lang` header to localize
`campaigns[].campaignName`.
operationId: previewEventRewards
parameters:
- name: lang
in: header
description: >-
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.
required: false
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customerId
- events
properties:
customerId:
type: string
maxLength: 100
description: >-
The customer's unique ID in your system. Must be an
existing, active customer.
example: '1214'
email:
type: string
description: Used only to help locate the customer (channel merge).
mobile:
type: string
description: Used only to help locate the customer (channel merge).
events:
type: object
description: >-
One entry per event to preview: the key is the event name,
the value is that event's metadata object (or `{}` / `null`
if none).
additionalProperties:
type:
- object
- 'null'
additionalProperties: true
example:
add_review:
rating: 5
examples:
sample:
summary: Sample request
value:
customerId: '1214'
events:
add_review:
rating: 5
responses:
'200':
description: Event reward preview calculated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/EventRewardPreviewResponse'
examples:
sample:
value:
customerId: '1214'
totalPoints: 150
events:
- eventName: add_review
valid: true
invalidReason: null
totalPoints: 150
campaigns:
- campaignId: 2655
campaignName: Review & Earn
campaignEndDate: '2026-08-31T23:59:59Z'
eligible: true
reason: Rewarded
rewardType: Points
rewardPoints: 150
couponType: null
couponValue: null
points: 150
timesAchieved: 1
progress: null
- campaignId: 2656
campaignName: Review Coupon
campaignEndDate: null
eligible: true
reason: NonPointsReward
rewardType: Coupon
rewardPoints: null
couponType: Percentage
couponValue: 10
points: 0
timesAchieved: 1
progress: null
'400':
description: >-
Missing or invalid payload, missing `customerId` or `events`, or a
key/value exceeding the maximum string length.
'401':
description: Missing or invalid API key or secret key.
'404':
description: >-
The customer does not exist. Inactive or excluded customers also
fail.
security:
- apiKey: []
components:
schemas:
EventRewardPreviewResponse:
type: object
properties:
customerId:
type: string
description: Echo of the request.
totalPoints:
type: integer
description: Sum of points across all previewed events.
events:
type: array
description: One independent result per event sent, in request order.
items:
$ref: '#/components/schemas/RewardPreviewEventResult'
RewardPreviewEventResult:
type: object
properties:
eventName:
type: string
description: The event name as sent.
valid:
type: boolean
description: >-
`false` when the event itself could not be evaluated (see
`invalidReason`). Other events in the same request still return
results.
invalidReason:
type:
- string
- 'null'
description: >-
Set when `valid` is `false`: `EventNotFound`, `InvalidMetadata:
...`, or `PreviewFailed`.
totalPoints:
type: integer
description: Points this event would earn now, across all its campaigns.
campaigns:
type: array
description: >-
Per-campaign breakdown. Empty when the event matches no campaign —
that is still a success with 0 points. Campaigns the customer can no
longer win are omitted.
items:
$ref: '#/components/schemas/RewardPreviewCampaign'
RewardPreviewCampaign:
type: object
properties:
campaignId:
type: integer
description: Campaign identifier.
campaignName:
type: string
description: >-
Campaign display name, translated for the `lang` header (falls back
to your account's default language, then to the campaign's internal
name).
campaignEndDate:
type:
- string
- 'null'
format: date-time
description: >-
Campaign end date — use it for urgency messaging. `null` for
open-ended campaigns.
eligible:
type: boolean
description: >-
`true` when the event would progress or achieve this campaign now;
`false` only when the campaign is linked to the event but the sent
metadata satisfied none of its conditions.
reason:
type: string
enum:
- Rewarded
- ProgressOnly
- NoMatchingConditions
- NonPointsReward
description: Outcome of evaluating this campaign for the previewed event.
rewardType:
type: string
enum:
- Points
- Coupon
description: What this campaign's reward is.
rewardPoints:
type:
- integer
- 'null'
description: >-
The campaign's configured points reward (its offer), shown
regardless of outcome. `null` when the reward is a coupon.
couponType:
type:
- string
- 'null'
description: >-
Coupon kind when the reward is a coupon (e.g. `Fixed`, `Percentage`,
`FreeShipping`). Machine-readable — no real code is generated by a
preview.
couponValue:
type:
- number
- 'null'
description: >-
The coupon's configured value (amount or percentage, per
`couponType`).
points:
type: integer
description: >-
Points the customer would actually earn now from this campaign
(already multiplied by `timesAchieved`). `0` for progress-only and
coupon outcomes.
timesAchieved:
type: integer
description: >-
How many times this single event would achieve the campaign (can
exceed 1 for accumulative campaigns; `0` when it only advances
progress).
progress:
oneOf:
- $ref: '#/components/schemas/RewardPreviewProgress'
- type: 'null'
RewardPreviewProgress:
type: object
description: >-
Present only for `ProgressOnly` — accumulative / multi-step campaigns
the event advances without completing.
properties:
currentPercentage:
type: number
description: Completion % (0–100) before this event.
wouldBePercentage:
type: number
description: Completion % (0–100, capped) after this event fires.
completionRewardPoints:
type:
- integer
- 'null'
description: >-
Points granted when the campaign eventually completes; `null` when
the completion reward is a coupon.
completionRewardType:
type: string
description: '`Points` or `Coupon`.'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
apiKey:
type: apiKey
in: header
name: apikey
````