Orders

Order Points Breakdown

Changed on

Returns a line-by-line explanation of how a customer earned their 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's earning transaction.

Use it to answer "why did I get these points?" in a receipt or order-details screen, and to reconcile a customer's balance against a specific purchase.

The breakdown is built from the order's earning transaction (PaymentReward). An order that never earned points — dropped, fully excluded, or not yet processed — returns 404.

This endpoint is available on v4.0 and v4.1.

Security: Requires both apikey and secretkey headers. The secret key is required on both versions, whether or not High Security Mode is enabled on the account.

Localization: Send the optional lang header to localize tierName and items[].campaignName.

get/api/v4.0/integrations/orders/{orderId}/points-breakdown

Request

  • Base URL: https://api.gameball.co
  • URL: https://api.gameball.co/api/v4.0/integrations/orders/{orderId}/points-breakdown
  • Auth: API key in header apikey and API key in header secretkey

Path parameters

orderIdstring required

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

Headers

langstring

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.

Response

Points breakdown retrieved successfully

transactionIdinteger

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

transactionTypestring

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

isReversedboolean

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

earnedPointsinteger

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

pointsValuenumber nullable

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

orderAmountnumber nullable

The order amount the reward was calculated on.

currencystring nullable

Currency of orderAmount and pointsValue.

customerIdstring

The customer's unique identifier in your system.

tierNamestring nullable

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

transactionTimestring date-time

When the earning transaction was recorded.

expiryDatestring date-time nullable

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

pointsBalanceBeforeinteger

The customer's points balance immediately before this transaction.

excludeTaxesboolean

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

excludeNonProductCostsboolean

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

usedCouponCodesstring[]

Coupon codes applied to the order.

redeemedPointsinteger

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.

redeemedAmountnumber

Monetary value of the redeemed points.

hasRedemptionboolean

true when the order included a redemption.

itemsExactTotalnumber

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

roundedDownAtOrderLevelboolean

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

roundedDownAmountnumber

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

reconcilesboolean

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

hasItemBreakdownboolean

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

Example response

{
  "transactionId": 11034754,
  "transactionType": "Payment Reward",
  "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": "Excluded by the store's rule: item product id is P-900",
      "pricePerUnit": 180,
      "lineSubtotal": 180,
      "discount": 20,
      "totalDiscount": 20,
      "eligibleAmount": 160,
      "sourceKind": "level",
      "sourceLabel": "Gold earning rate",
      "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
    }
  ],
  "itemsExactTotal": 192,
  "reconciles": true,
  "hasItemBreakdown": true
}

Changes