Order Points Breakdown
Explain how a customer earned their points on a specific order, item by item.
GET
Order Points Breakdown
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
What the breakdown is built from
The breakdown explains the order’s earning transaction — thePaymentReward 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.
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 initems carries the full trace for one product line:
1
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.2
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.3
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.4
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.
roundedPerLinemarks a line that lost a fraction this way. - Non-campaign lines stay fractional and are floored once at the order total.
roundedDownAtOrderLevelandroundedDownAmountreport 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 returnhasItemBreakdown: 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 throughredeemedPoints, redeemedAmount, and hasRedemption. Redemption value is already folded into the line discounts, so it is never attributed to a single item.
Localization
Send the optionallang 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.Headers
Path Parameters
Response
Points breakdown retrieved successfully
Item-by-item explanation of the points earned on one order.