---
title: "Preview Event Rewards"
method: POST
path: "/api/v4.0/integrations/events/reward-preview"
tags: ["Events"]
---

# Preview Event Rewards

`POST /api/v4.0/integrations/events/reward-preview`

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`.

## Headers

- `lang` string

## Request body

- object
  - `customerId` string, required — The customer's unique ID in your system. Must be an existing, active customer.
  - `email` string — Used only to help locate the customer (channel merge).
  - `mobile` string — Used only to help locate the customer (channel merge).
  - `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).

## Response `200`

Event reward preview calculated successfully

- EventRewardPreviewResponse
  - `customerId` string — Echo of the request.
  - `totalPoints` integer — Sum of points across all previewed events.
  - `events` RewardPreviewEventResult[] — One independent result per event sent, in request order.
    - `eventName` string — The event name as sent.
    - `valid` boolean — `false` when the event itself could not be evaluated (see `invalidReason`). Other events in the same request still return results.
    - `invalidReason` string, nullable — Set when `valid` is `false`: `EventNotFound`, `InvalidMetadata: ...`, or `PreviewFailed`.
    - `totalPoints` integer — Points this event would earn now, across all its campaigns.
    - `campaigns` RewardPreviewCampaign[] — 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.
      - `campaignId` integer — Campaign identifier.
      - `campaignName` string — Campaign display name, translated for the `lang` header (falls back to your account's default language, then to the campaign's internal name).
      - `campaignEndDate` string, date-time, nullable — Campaign end date — use it for urgency messaging. `null` for open-ended campaigns.
      - `eligible` boolean — `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` 'Rewarded' | 'ProgressOnly' | 'NoMatchingConditions' | 'NonPointsReward' — Outcome of evaluating this campaign for the previewed event.
      - `rewardType` 'Points' | 'Coupon' — What this campaign's reward is.
      - `rewardPoints` integer, nullable — The campaign's configured points reward (its offer), shown regardless of outcome. `null` when the reward is a coupon.
      - `couponType` string, nullable — Coupon kind when the reward is a coupon (e.g. `Fixed`, `Percentage`, `FreeShipping`). Machine-readable — no real code is generated by a preview.
      - `couponValue` number, nullable — The coupon's configured value (amount or percentage, per `couponType`).
      - `points` integer — Points the customer would actually earn now from this campaign (already multiplied by `timesAchieved`). `0` for progress-only and coupon outcomes.
      - `timesAchieved` integer — How many times this single event would achieve the campaign (can exceed 1 for accumulative campaigns; `0` when it only advances progress).
      - `progress` RewardPreviewProgress — Present only for `ProgressOnly` — accumulative / multi-step campaigns the event advances without completing.
        - `currentPercentage` number — Completion % (0–100) before this event.
        - `wouldBePercentage` number — Completion % (0–100, capped) after this event fires.
        - `completionRewardPoints` integer, nullable — Points granted when the campaign eventually completes; `null` when the completion reward is a coupon.
        - `completionRewardType` string — `Points` or `Coupon`.

## Other responses

- `400` — Missing or invalid payload, missing `customerId` or `events`, or a key/value exceeding the maximum string length.
- `401` — Missing or invalid API key or secret key.
- `404` — The customer does not exist. Inactive or excluded customers also fail.

---

[API](https://skmtc.net/gameballers/apis/gameball-api.md) · [All operations](https://skmtc.net/gameballers/apis/gameball-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gameballers/gameball-api/revisions/3b11e1670d61/schema)