> ## 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 Order Rewards > Quote cashback points and place_order campaign rewards for a cart or checkout before anything is awarded. Combined order preview: the **order cashback quote** (identical calculation to [Calculate Order Cashback](/api-reference/order/calculate-order-cashback)) **plus** a preview of the **event-based campaigns** the order would trigger (the order is evaluated as the same `place_order` event a real order submission fires). Use this on cart and checkout pages to show everything the order will earn in one call. 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. **Security:** Provide `apikey` header. `secretkey` is required on v4.1; on v4.0 required when High Security Mode is enabled. ### Customer handling The cashback quote works without an existing customer (useful for guest checkout). Campaign eligibility requires an existing customer: * When the customer is found: `customerFound` is `true` and `eventRewards` includes the `place_order` campaign breakdown. * When the customer is missing or inactive: `customerFound` is `false`, the cashback quote is still returned, and `eventRewards` is `null`. ### Localization Send the optional `lang` header to localize `eventRewards.campaigns[].campaignName`. Cashback `campaignName` values use the campaign's **internal** name (matching Calculate Order Cashback) and are not affected by `lang`. For event campaign `reason` values and other machine-readable fields, see [Preview Event Rewards](/api-reference/events/preview-event-rewards). ### Notes and limitations * Previews are point-in-time quotes. A concurrent real order 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. Actual coupon codes are generated only by real orders. * The order preview evaluates the order-level `place_order` event only. Campaigns built on the internal per-item purchase event are not included. * The order preview has no `orderId` (same as Calculate Order Cashback), so campaign conditions that reference the `order_id` metadata key will not match in a preview. * Unknown metadata keys are ignored by previews. * Streak badges and mission step rewards are not included in preview results. For custom (non-order) events, use [Preview Event Rewards](/api-reference/events/preview-event-rewards). ## OpenAPI ````yaml POST /api/v4.0/integrations/orders/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/orders/reward-preview: post: tags: - Orders summary: Preview Order Rewards description: >- 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`. operationId: previewOrderRewards parameters: - name: lang in: header description: >- Language code for localized campaign names in `eventRewards.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: - totalPaid properties: customerId: type: string maxLength: 100 description: >- 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`. 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). totalPaid: type: number minimum: 0 description: Amount actually paid. example: 90 totalPrice: type: number minimum: 0 description: Order total before discounts. example: 100 totalDiscount: type: number minimum: 0 description: Total discount applied. example: 10 totalShipping: type: number minimum: 0 description: Shipping total. totalTax: type: number minimum: 0 description: Tax total. lineItems: type: array description: Order line items. items: type: object properties: productId: type: string description: Product identifier. example: P-100 sku: type: string description: Product SKU. example: SKU-100 title: type: string description: Product title. example: Running Shoes quantity: type: number minimum: 0 description: Quantity purchased. example: 1 price: type: number minimum: 0 description: Unit price. example: 100 discount: type: number minimum: 0 description: >- Line discount total (must not exceed the gross line total). example: 10 taxes: type: number minimum: 0 description: Line taxes. weight: type: number minimum: 0 description: Item weight. vendor: type: string description: Vendor/supplier name. tags: type: array items: type: string description: Product tags — usable in campaign conditions. category: type: array items: type: string description: Product categories — usable in campaign conditions. example: - shoes collection: type: array items: type: string description: Product collections — usable in campaign conditions. extra: type: object additionalProperties: true description: Custom line-item attributes. merchant: type: object description: Merchant/branch info for multi-merchant setups. properties: uniqueId: type: string name: type: string branch: type: object properties: uniqueId: type: string name: type: string channel: type: string description: Order channel (e.g. `web`, `pos`, `mobile`). example: web extra: type: object additionalProperties: true description: Custom key/value attributes — usable in campaign conditions. examples: sample: summary: Sample request value: customerId: '1214' totalPaid: 90 totalPrice: 100 totalDiscount: 10 channel: web lineItems: - productId: P-100 sku: SKU-100 title: Running Shoes quantity: 1 price: 100 discount: 10 category: - shoes responses: '200': description: Order reward preview calculated successfully content: application/json: schema: $ref: '#/components/schemas/OrderRewardPreviewResponse' examples: sample: value: customerId: '1214' customerFound: true totalPoints: 270 totalCoupons: 1 cashback: totalPoints: 120 totalScore: 120 lineItems: - productId: P-100 quantity: 1 totalPoints: 120 totalScore: 120 totalDecimalPoints: 120 rewardWalletFactor: 1.2 campaignId: 3101 campaignName: Double Points Week campaignEndDate: '2026-08-15T23:59:59Z' campaignImpactPoints: 60 campaignImpactWalletFactor: 0.6 eventRewards: eventName: place_order valid: true invalidReason: null totalPoints: 150 campaigns: - campaignId: 2655 campaignName: First Order Bonus campaignEndDate: null eligible: true reason: Rewarded rewardType: Points rewardPoints: 150 couponType: null couponValue: null points: 150 timesAchieved: 1 progress: null - campaignId: 2656 campaignName: Order Coupon Gift 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 (e.g. negative amounts, discount exceeding a line's total). '401': description: Missing or invalid API key or secret key. security: - apiKey: [] components: schemas: OrderRewardPreviewResponse: type: object properties: customerId: type: string description: Echo of the request. customerFound: type: boolean description: >- `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: type: integer description: >- Grand total: cashback points + points from event campaigns the order would achieve now. totalCoupons: type: integer description: >- Number of coupons the order's event campaigns would grant (one per achievement of a coupon-reward campaign). cashback: type: object description: >- 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. properties: totalPoints: type: number description: Total cashback points expected from the order. totalScore: type: number description: Total score expected from the order. lineItems: type: array items: type: object properties: productId: type: string quantity: type: number totalPoints: type: number totalScore: type: number totalDecimalPoints: type: number rewardWalletFactor: type: number campaignId: type: - integer - 'null' campaignName: type: - string - 'null' description: Internal campaign name (not localized by `lang`). campaignEndDate: type: - string - 'null' format: date-time campaignImpactPoints: type: number campaignImpactWalletFactor: type: number eventRewards: oneOf: - $ref: '#/components/schemas/RewardPreviewEventResult' - type: 'null' description: >- The `place_order` event preview — exactly one entry with the same shape as an `events[]` entry of Preview Event Rewards. 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 ````