---
title: "Preview Order Rewards"
method: POST
path: "/api/v4.0/integrations/orders/reward-preview"
tags: ["Orders"]
---

# Preview Order Rewards

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

Preview everything an order would earn before checkout: the order cashback quote (identical calculation to Calculate Order Cashback) plus a preview of the event-based campaigns the order would trigger (evaluated as the same `place_order` event a real order submission fires).

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.

**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 `eventRewards.campaigns[].campaignName`. Cashback `campaignName` values use the campaign's internal name and are not affected by `lang`.

## Headers

- `lang` string

## Request body

- object
  - `customerId` string — The customer's unique ID. The cashback part works without it (quote for a new customer); the campaigns part requires an existing customer — see `customerFound`.
  - `email` string — Used only to help locate the customer (channel merge).
  - `mobile` string — Used only to help locate the customer (channel merge).
  - `totalPaid` number, required — Amount actually paid.
  - `totalPrice` number — Order total before discounts.
  - `totalDiscount` number — Total discount applied.
  - `totalShipping` number — Shipping total.
  - `totalTax` number — Tax total.
  - `lineItems` object[] — Order line items.
    - `productId` string — Product identifier.
    - `sku` string — Product SKU.
    - `title` string — Product title.
    - `quantity` number — Quantity purchased.
    - `price` number — Unit price.
    - `discount` number — Line discount total (must not exceed the gross line total).
    - `taxes` number — Line taxes.
    - `weight` number — Item weight.
    - `vendor` string — Vendor/supplier name.
    - `tags` string[] — Product tags — usable in campaign conditions.
    - `category` string[] — Product categories — usable in campaign conditions.
    - `collection` string[] — Product collections — usable in campaign conditions.
    - `extra` object — Custom line-item attributes.
  - `merchant` object — Merchant/branch info for multi-merchant setups.
    - `uniqueId` string
    - `name` string
    - `branch` object
      - `uniqueId` string
      - `name` string
  - `channel` string — Order channel (e.g. `web`, `pos`, `mobile`).
  - `extra` object — Custom key/value attributes — usable in campaign conditions.

## Response `200`

Order reward preview calculated successfully

- OrderRewardPreviewResponse
  - `customerId` string — Echo of the request.
  - `customerFound` boolean — `false` when the customer does not exist or is inactive. The cashback quote is still returned; `eventRewards` is `null` (campaign eligibility can't be evaluated without an existing customer).
  - `totalPoints` integer — Grand total: cashback points + points from event campaigns the order would achieve now.
  - `totalCoupons` integer — Number of coupons the order's event campaigns would grant (one per achievement of a coupon-reward campaign).
  - `cashback` object — The cashback quote — same shape as the Calculate Order Cashback response. Note: `campaignName` here is the campaign's internal name and is not affected by the `lang` header.
    - `totalPoints` number — Total cashback points expected from the order.
    - `totalScore` number — Total score expected from the order.
    - `lineItems` object[]
      - `productId` string
      - `quantity` number
      - `totalPoints` number
      - `totalScore` number
      - `totalDecimalPoints` number
      - `rewardWalletFactor` number
      - `campaignId` integer, nullable
      - `campaignName` string, nullable — Internal campaign name (not localized by `lang`).
      - `campaignEndDate` string, date-time, nullable
      - `campaignImpactPoints` number
      - `campaignImpactWalletFactor` number
  - `eventRewards` RewardPreviewEventResult
    - `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 (e.g. negative amounts, discount exceeding a line's total).
- `401` — Missing or invalid API key or secret key.

---

[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)