Preview Order Rewards

curl --request POST \
  --url https://api.gameball.co/api/v4.0/integrations/orders/reward-preview \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "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"
      ]
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {apikey: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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']
      }
    ]
  })
};

fetch('https://api.gameball.co/api/v4.0/integrations/orders/reward-preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gameball.co/api/v4.0/integrations/orders/reward-preview"

payload = {
    "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"]
        }
    ]
}
headers = {
    "apikey": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

using RestSharp;


var options = new RestClientOptions("https://api.gameball.co/api/v4.0/integrations/orders/reward-preview");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("apikey", "<api-key>");
request.AddJsonBody("{\n  \"customerId\": \"1214\",\n  \"totalPaid\": 90,\n  \"totalPrice\": 100,\n  \"totalDiscount\": 10,\n  \"channel\": \"web\",\n  \"lineItems\": [\n    {\n      \"productId\": \"P-100\",\n      \"sku\": \"SKU-100\",\n      \"title\": \"Running Shoes\",\n      \"quantity\": 1,\n      \"price\": 100,\n      \"discount\": 10,\n      \"category\": [\n        \"shoes\"\n      ]\n    }\n  ]\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gameball.co/api/v4.0/integrations/orders/reward-preview"

	payload := strings.NewReader("{\n  \"customerId\": \"1214\",\n  \"totalPaid\": 90,\n  \"totalPrice\": 100,\n  \"totalDiscount\": 10,\n  \"channel\": \"web\",\n  \"lineItems\": [\n    {\n      \"productId\": \"P-100\",\n      \"sku\": \"SKU-100\",\n      \"title\": \"Running Shoes\",\n      \"quantity\": 1,\n      \"price\": 100,\n      \"discount\": 10,\n      \"category\": [\n        \"shoes\"\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("apikey", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gameball.co/api/v4.0/integrations/orders/reward-preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "apikey: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.gameball.co/api/v4.0/integrations/orders/reward-preview")
  .header("apikey", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerId\": \"1214\",\n  \"totalPaid\": 90,\n  \"totalPrice\": 100,\n  \"totalDiscount\": 10,\n  \"channel\": \"web\",\n  \"lineItems\": [\n    {\n      \"productId\": \"P-100\",\n      \"sku\": \"SKU-100\",\n      \"title\": \"Running Shoes\",\n      \"quantity\": 1,\n      \"price\": 100,\n      \"discount\": 10,\n      \"category\": [\n        \"shoes\"\n      ]\n    }\n  ]\n}")
  .asString();

{
  "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
      }
    ]
  }
}

POST

api

v4.0

integrations

orders

reward-preview

Preview Order Rewards

curl --request POST \
  --url https://api.gameball.co/api/v4.0/integrations/orders/reward-preview \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "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"
      ]
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {apikey: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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']
      }
    ]
  })
};

fetch('https://api.gameball.co/api/v4.0/integrations/orders/reward-preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gameball.co/api/v4.0/integrations/orders/reward-preview"

payload = {
    "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"]
        }
    ]
}
headers = {
    "apikey": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

using RestSharp;


var options = new RestClientOptions("https://api.gameball.co/api/v4.0/integrations/orders/reward-preview");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("apikey", "<api-key>");
request.AddJsonBody("{\n  \"customerId\": \"1214\",\n  \"totalPaid\": 90,\n  \"totalPrice\": 100,\n  \"totalDiscount\": 10,\n  \"channel\": \"web\",\n  \"lineItems\": [\n    {\n      \"productId\": \"P-100\",\n      \"sku\": \"SKU-100\",\n      \"title\": \"Running Shoes\",\n      \"quantity\": 1,\n      \"price\": 100,\n      \"discount\": 10,\n      \"category\": [\n        \"shoes\"\n      ]\n    }\n  ]\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gameball.co/api/v4.0/integrations/orders/reward-preview"

	payload := strings.NewReader("{\n  \"customerId\": \"1214\",\n  \"totalPaid\": 90,\n  \"totalPrice\": 100,\n  \"totalDiscount\": 10,\n  \"channel\": \"web\",\n  \"lineItems\": [\n    {\n      \"productId\": \"P-100\",\n      \"sku\": \"SKU-100\",\n      \"title\": \"Running Shoes\",\n      \"quantity\": 1,\n      \"price\": 100,\n      \"discount\": 10,\n      \"category\": [\n        \"shoes\"\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("apikey", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gameball.co/api/v4.0/integrations/orders/reward-preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "apikey: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.gameball.co/api/v4.0/integrations/orders/reward-preview")
  .header("apikey", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerId\": \"1214\",\n  \"totalPaid\": 90,\n  \"totalPrice\": 100,\n  \"totalDiscount\": 10,\n  \"channel\": \"web\",\n  \"lineItems\": [\n    {\n      \"productId\": \"P-100\",\n      \"sku\": \"SKU-100\",\n      \"title\": \"Running Shoes\",\n      \"quantity\": 1,\n      \"price\": 100,\n      \"discount\": 10,\n      \"category\": [\n        \"shoes\"\n      ]\n    }\n  ]\n}")
  .asString();

{
  "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
      }
    ]
  }
}

Combined order preview: the order cashback quote (identical calculation to 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.

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.

Authorizations

apikey

string

header

required

Headers

lang

string

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.

Body

application/json

totalPaid

number

required

Amount actually paid.

Required range: x >= 0

Example:

90

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.

Maximum string length: 100

Example:

"1214"

string

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

mobile

string

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

totalPrice

number

Order total before discounts.

Required range: x >= 0

Example:

100

totalDiscount

number

Total discount applied.

Required range: x >= 0

Example:

10

totalShipping

number

Shipping total.

Required range: x >= 0

totalTax

number

Tax total.

Required range: x >= 0

lineItems

object[]

Order line items.

Show child attributes

merchant

object

Merchant/branch info for multi-merchant setups.

Show child attributes

channel

string

Order channel (e.g. web, pos, mobile).

Example:

"web"

extra

object

Custom key/value attributes — usable in campaign conditions.

Response

Order reward preview calculated successfully

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.

Show child attributes

eventRewards

object | null

The place_order event preview — exactly one entry with the same shape as an events[] entry of Preview Event Rewards.

Show child attributes

API documentation

Webhooks

Preview Order Rewards

Customer handling

Localization

Notes and limitations

Authorizations

Headers

Body

Response

​Customer handling

​Localization

​Notes and limitations

Authorizations

Headers

Body

Response

Customer handling

Localization

Notes and limitations