Order Points Breakdown

curl --request GET \
  --url https://api.gameball.co/api/v4.0/integrations/orders/{orderId}/points-breakdown \
  --header 'apikey: <api-key>' \
  --header 'secretkey: <api-key>'

const options = {method: 'GET', headers: {apikey: '<api-key>', secretkey: '<api-key>'}};

fetch('https://api.gameball.co/api/v4.0/integrations/orders/{orderId}/points-breakdown', 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/{orderId}/points-breakdown"

headers = {
    "apikey": "<api-key>",
    "secretkey": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

using RestSharp;


var options = new RestClientOptions("https://api.gameball.co/api/v4.0/integrations/orders/{orderId}/points-breakdown");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("apikey", "<api-key>");
request.AddHeader("secretkey", "<api-key>");
var response = await client.GetAsync(request);

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

package main

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

func main() {

	url := "https://api.gameball.co/api/v4.0/integrations/orders/{orderId}/points-breakdown"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("apikey", "<api-key>")
	req.Header.Add("secretkey", "<api-key>")

	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/{orderId}/points-breakdown",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "apikey: <api-key>",
    "secretkey: <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.get("https://api.gameball.co/api/v4.0/integrations/orders/{orderId}/points-breakdown")
  .header("apikey", "<api-key>")
  .header("secretkey", "<api-key>")
  .asString();

{
  "transactionId": 11034754,
  "transactionType": "Payment Reward",
  "isReversed": false,
  "earnedPoints": 192,
  "pointsValue": 19.2,
  "orderAmount": 230,
  "currency": "SAR",
  "customerId": "1214",
  "tierName": "Gold",
  "transactionTime": "2026-09-01T08:13:29.29",
  "expiryDate": "2027-09-01T00:00:00",
  "pointsBalanceBefore": 1340,
  "excludeTaxes": true,
  "excludeNonProductCosts": true,
  "usedCouponCodes": [
    "WELCOME10"
  ],
  "redeemedPoints": 200,
  "redeemedAmount": 20,
  "hasRedemption": true,
  "items": [
    {
      "title": "Running Shoes",
      "productId": "P-100",
      "sku": "SHOE-42-BLK",
      "quantity": 1,
      "eligible": true,
      "eligibilityMode": "General",
      "ineligibleReason": null,
      "pricePerUnit": 180,
      "lineSubtotal": 180,
      "discount": 20,
      "taxInDiscount": 0,
      "totalDiscount": 20,
      "eligibleAmount": 160,
      "sourceKind": "level",
      "sourceLabel": "Gold earning rate",
      "ruleCondition": null,
      "rewardFactor": 1,
      "amountThreshold": 1,
      "baseRate": 1,
      "basePoints": 160,
      "hasCampaign": true,
      "campaignName": "Double Points Week",
      "campaignTierBand": "100–500 SAR",
      "campaignCondition": "order total price at least 100",
      "campaignMultiplier": 1.2,
      "effectiveRate": 1.2,
      "itemPoints": 192,
      "roundedPerLine": false
    },
    {
      "title": "Gift Card 50",
      "productId": "P-900",
      "sku": "GC-50",
      "quantity": 1,
      "eligible": false,
      "eligibilityMode": "Exclude",
      "ineligibleReason": "Excluded by the store's rule: item product id is P-900",
      "pricePerUnit": 50,
      "lineSubtotal": 50,
      "discount": 0,
      "taxInDiscount": 0,
      "totalDiscount": 0,
      "eligibleAmount": 50,
      "sourceKind": "base",
      "sourceLabel": "Base rate",
      "ruleCondition": null,
      "rewardFactor": 1,
      "amountThreshold": 1,
      "baseRate": 1,
      "basePoints": 50,
      "hasCampaign": false,
      "campaignName": null,
      "campaignTierBand": null,
      "campaignCondition": null,
      "campaignMultiplier": null,
      "effectiveRate": 1,
      "itemPoints": 0,
      "roundedPerLine": false
    }
  ],
  "itemsExactTotal": 192,
  "roundedDownAtOrderLevel": false,
  "roundedDownAmount": 0,
  "reconciles": true,
  "hasItemBreakdown": true
}

GET

api

v4.0

integrations

orders

{orderId}

points-breakdown

Order Points Breakdown

curl --request GET \
  --url https://api.gameball.co/api/v4.0/integrations/orders/{orderId}/points-breakdown \
  --header 'apikey: <api-key>' \
  --header 'secretkey: <api-key>'

const options = {method: 'GET', headers: {apikey: '<api-key>', secretkey: '<api-key>'}};

fetch('https://api.gameball.co/api/v4.0/integrations/orders/{orderId}/points-breakdown', 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/{orderId}/points-breakdown"

headers = {
    "apikey": "<api-key>",
    "secretkey": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

using RestSharp;


var options = new RestClientOptions("https://api.gameball.co/api/v4.0/integrations/orders/{orderId}/points-breakdown");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("apikey", "<api-key>");
request.AddHeader("secretkey", "<api-key>");
var response = await client.GetAsync(request);

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

package main

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

func main() {

	url := "https://api.gameball.co/api/v4.0/integrations/orders/{orderId}/points-breakdown"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("apikey", "<api-key>")
	req.Header.Add("secretkey", "<api-key>")

	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/{orderId}/points-breakdown",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "apikey: <api-key>",
    "secretkey: <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.get("https://api.gameball.co/api/v4.0/integrations/orders/{orderId}/points-breakdown")
  .header("apikey", "<api-key>")
  .header("secretkey", "<api-key>")
  .asString();

{
  "transactionId": 11034754,
  "transactionType": "Payment Reward",
  "isReversed": false,
  "earnedPoints": 192,
  "pointsValue": 19.2,
  "orderAmount": 230,
  "currency": "SAR",
  "customerId": "1214",
  "tierName": "Gold",
  "transactionTime": "2026-09-01T08:13:29.29",
  "expiryDate": "2027-09-01T00:00:00",
  "pointsBalanceBefore": 1340,
  "excludeTaxes": true,
  "excludeNonProductCosts": true,
  "usedCouponCodes": [
    "WELCOME10"
  ],
  "redeemedPoints": 200,
  "redeemedAmount": 20,
  "hasRedemption": true,
  "items": [
    {
      "title": "Running Shoes",
      "productId": "P-100",
      "sku": "SHOE-42-BLK",
      "quantity": 1,
      "eligible": true,
      "eligibilityMode": "General",
      "ineligibleReason": null,
      "pricePerUnit": 180,
      "lineSubtotal": 180,
      "discount": 20,
      "taxInDiscount": 0,
      "totalDiscount": 20,
      "eligibleAmount": 160,
      "sourceKind": "level",
      "sourceLabel": "Gold earning rate",
      "ruleCondition": null,
      "rewardFactor": 1,
      "amountThreshold": 1,
      "baseRate": 1,
      "basePoints": 160,
      "hasCampaign": true,
      "campaignName": "Double Points Week",
      "campaignTierBand": "100–500 SAR",
      "campaignCondition": "order total price at least 100",
      "campaignMultiplier": 1.2,
      "effectiveRate": 1.2,
      "itemPoints": 192,
      "roundedPerLine": false
    },
    {
      "title": "Gift Card 50",
      "productId": "P-900",
      "sku": "GC-50",
      "quantity": 1,
      "eligible": false,
      "eligibilityMode": "Exclude",
      "ineligibleReason": "Excluded by the store's rule: item product id is P-900",
      "pricePerUnit": 50,
      "lineSubtotal": 50,
      "discount": 0,
      "taxInDiscount": 0,
      "totalDiscount": 0,
      "eligibleAmount": 50,
      "sourceKind": "base",
      "sourceLabel": "Base rate",
      "ruleCondition": null,
      "rewardFactor": 1,
      "amountThreshold": 1,
      "baseRate": 1,
      "basePoints": 50,
      "hasCampaign": false,
      "campaignName": null,
      "campaignTierBand": null,
      "campaignCondition": null,
      "campaignMultiplier": null,
      "effectiveRate": 1,
      "itemPoints": 0,
      "roundedPerLine": false
    }
  ],
  "itemsExactTotal": 192,
  "roundedDownAtOrderLevel": false,
  "roundedDownAmount": 0,
  "reconciles": true,
  "hasItemBreakdown": true
}

Retrieve a line-by-line explanation of how a customer earned points on a specific order: which items were eligible, the earning rate applied to each one, any campaign multiplier that boosted it, and how the per-item points add up to the total recorded on the order. Use it to power a “why did I get these points?” receipt in your order-details screen, and to reconcile a customer’s balance against a specific purchase. This endpoint is available on v4.0 and v4.1.

Security: Requires apikey and secretkey headers. The secret key is required on both v4.0 and v4.1, whether or not High Security Mode is enabled on your account.

Headers

Header	Required	Value
`apikey`	Yes	Your Gameball API key.
`secretkey`	Yes	Your Gameball secret key. Always required on this endpoint, on both `v4.0` and `v4.1`.
`lang`	No	Language code for localized names in the response (e.g. `en`, `ar`, `fr`). Defaults to your account’s default language — see Localization.

What the breakdown is built from

The breakdown explains the order’s earning transaction — the PaymentReward transaction recorded when the order was processed. It is a read-only explanation of points that were already awarded, not a quote:

To quote points before checkout, use Calculate Order Cashback or Preview Order Rewards.
To list every transaction tied to an order (rewards, refunds, redemptions), use Order Transactions.

An order that never earned points returns 404. That happens when the order was never tracked, was dropped, had every line excluded from earning, or has not finished processing yet.

Orders are processed asynchronously. Immediately after Order Tracking returns 202, the earning transaction may not exist yet and this endpoint returns 404. Retry, or call it from a screen the customer opens after the order is complete.

Reading the item math

Each entry in items carries the full trace for one product line:

Eligibility

eligible says whether the line earned anything, and eligibilityMode says which rule decided it (General, Include, Exclude, Merchant, or Custom). When a line earned nothing, ineligibleReason explains why in plain language.

Money base

eligibleAmount is the amount points were calculated on, after discount and any tax or non-product exclusions. lineSubtotal is the pre-discount total, and pricePerUnit is that divided by quantity.

Rate

baseRate comes from the rule named by sourceKind and sourceLabel (the account’s base rate, the customer’s tier rate, or a custom rule). It is the dashboard rule expressed per unit of currency: a rule reading “earn 5 points for every 10 spent” arrives as rewardFactor: 5, amountThreshold: 10, and baseRate: 0.5. When a campaign applies, campaignMultiplier boosts it into effectiveRate.

Points

basePoints is what the line would have earned with no campaign; itemPoints is what it actually contributed.

Rounding and reconciliation

earnedPoints is authoritative — it is the value recorded on the transaction and reflected in the customer’s balance. itemsExactTotal is the exact, unrounded sum of the eligible lines, so the two can differ by a fraction of a point:

Campaign lines are floored to whole points per line. roundedPerLine marks a line that lost a fraction this way.
Non-campaign lines stay fractional and are floored once at the order total. roundedDownAtOrderLevel and roundedDownAmount report that drop.

reconciles is true when the item breakdown explains the recorded total. A false value means the stored line items do not fully account for earnedPoints, so present the order-level figures rather than the per-item math.

Orders without line items

Orders recorded without line items return hasItemBreakdown: false and an empty items array. The order-level fields (earnedPoints, orderAmount, tierName, redeemedPoints, and the rest) are still populated.

Redemptions

Points the customer redeemed on the order are reported at order level through redeemedPoints, redeemedAmount, and hasRedemption. Redemption value is already folded into the line discounts, so it is never attributed to a single item.

Localization

Send the optional lang header to localize tierName and items[].campaignName. If the language is omitted or not configured in your account, the response falls back to your account’s default language.

Authorizations

apikey

string

header

required

secretkey

string

header

required

Headers

lang

string

Language code used to localize tierName and items[].campaignName (e.g., en, ar, fr). If omitted or not configured in your account, the response falls back to your account's default language.

Path Parameters

orderId

string

required

The order identifier in your system, the same value sent as orderId when the order was tracked. Case-sensitive.

Response

Points breakdown retrieved successfully

Item-by-item explanation of the points earned on one order.

transactionId

integer<int64>

Gameball's internal identifier for the earning transaction this breakdown explains.

Example:

11034754

transactionType

string

Display name of the transaction type the breakdown was built from.

Example:

"Payment Reward"

isReversed

boolean

true when the transaction type is a deduction (a reversal) rather than an earning.

Example:

false

earnedPoints

integer

The points actually recorded on the transaction. This is the authoritative total; itemsExactTotal explains it.

Example:

192

pointsValue

number | null

Monetary value of the earned points, when the transaction recorded one.

Example:

19.2

orderAmount

number | null

The order amount the reward was calculated on.

Example:

230

currency

string | null

Currency of orderAmount and pointsValue.

Example:

"SAR"

customerId

string

The customer's unique identifier in your system.

Example:

"1214"

tierName

string | null

The tier the customer was in when the order was rewarded, localized by the lang header when available.

Example:

"Gold"

transactionTime

string<date-time>

When the earning transaction was recorded.

Example:

"2026-09-01T08:13:29.29"

expiryDate

string<date-time> | null

When these earned points expire, when points expiry is enabled.

Example:

"2027-09-01T00:00:00"

pointsBalanceBefore

integer

The customer's points balance immediately before this transaction.

Example:

1340

excludeTaxes

boolean

Whether taxes were excluded from the earning base for this order.

Example:

true

excludeNonProductCosts

boolean

Whether shipping and other non-product costs were excluded from the earning base.

Example:

true

usedCouponCodes

string[]

Coupon codes applied to the order.

Example:

["WELCOME10"]

redeemedPoints

integer

Points the customer redeemed on this order. Redemption value is already folded into the line discounts, so it is reported at order level rather than attributed to any single line.

Example:

200

redeemedAmount

number

Monetary value of the redeemed points.

Example:

20

hasRedemption

boolean

true when the order included a redemption.

Example:

true

items

object[]

Per-line breakdown. Empty when the order was recorded without line items.

Show child attributes

itemsExactTotal

number

Exact, unrounded sum of items[].itemPoints for eligible lines. Compare against earnedPoints to see rounding.

Example:

192

roundedDownAtOrderLevel

boolean

true when a non-campaign order lost a sub-point fraction to flooring at the order total.

Example:

false

roundedDownAmount

number

The fraction of a point dropped by order-level flooring. 0 when nothing was dropped.

Example:

0

reconciles

boolean

true when itemsExactTotal explains earnedPoints (within one point). false means the stored line items do not fully account for the recorded total.

Example:

true

hasItemBreakdown

boolean

false when the order was recorded without line items, in which case items is empty and only the order-level figures are meaningful.

Example:

true

API documentation

Webhooks

Order Points Breakdown

Headers

What the breakdown is built from

Reading the item math

Rounding and reconciliation

Orders without line items

Redemptions

Localization

Authorizations

Headers

Path Parameters

Response

​Headers

​What the breakdown is built from

​Reading the item math

​Rounding and reconciliation

​Orders without line items

​Redemptions

​Localization

Authorizations

Headers

Path Parameters

Response

Headers

What the breakdown is built from

Reading the item math

Rounding and reconciliation

Orders without line items

Redemptions

Localization