Skip to main content

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.

​
Order Calculation Examples

This guide provides practical examples showing how to structure Order API payloads for common commerce scenarios including discounts, points redemption, coupons, and external loyalty programs. Endpoint: POST https://api.gameball.co/api/v4.0/integrations/orders Headers: 
apikey: {your-api-key}
secretkey: {your-secret-key}
Content-Type: application/json

​
Field Definitions

​
Line Item Fields

FieldDefinitionExample
priceUnit price of a single item (does NOT change with quantity)If 1 unit = $150, then price: 150 even if qty is 5
quantityNumber of unitsquantity: 2
discountTotal discount applied to this line item (NOT per unit)If $50 discount on 2 units, then discount: 50
taxesTotal tax for this line item after discount (NOT per unit)If line total after discount = $250 at 15% VAT, then taxes: 37.5

​
Order Level Fields

FieldDefinitionExample
totalPriceSum of all line items + taxes (before any discounts)Items = 500, Taxes = 75 → totalPrice: 575
totalDiscountSum of ALL discounts (line item + order level + points + coupon + external loyalty)Line discount 50 + Points 100 → totalDiscount: 150
totalTaxSum of all taxes across line itemstotalTax: 75
totalPaidWhat customer actually paid (totalPrice - totalDiscount)575 - 150 = totalPaid: 425

​
Redemption Fields

FieldDefinition
redemption.pointsHoldReferenceHold reference returned from the points hold API (Gameball points only)
redemption.couponsLockReferenceLock reference returned from the coupon lock API
redemption.couponCodesArray of coupon codes applied
Points are earned based on totalPaid only.

​
Calculation Formulas

​
Line Item Level

lineTotal = quantity × price

lineItemTax = (lineTotal - lineItemDiscount) × taxRate

​
Order Level

totalPrice = Σ(quantity × price) + Σ(taxes)

totalDiscount = Σ(lineItem.discount) + orderLevelDiscount + redemption + couponDiscount

totalPaid = totalPrice - totalDiscount

​
Example 1: Basic Order

Scenario: Customer purchases items at full price with no discounts or redemptions applied.
ComponentCalculationValue
Vitamin C (2 × $150)$300
Face Moisturizer (1 × $200)$200
Subtotal$500
Vitamin C Tax$300 × 15%$45
Face Moisturizer Tax$200 × 15%$30
Total Tax$75
totalPrice500 + 75$575
totalDiscount$0
totalPaid575 - 0$575
{
  "customerId": "+11234567890",
  "orderId": "INV-2026-001234",
  "orderDate": "2026-03-25T14:30:00Z",
  "totalPrice": 575,
  "totalDiscount": 0,
  "totalTax": 75,
  "totalPaid": 575,
  "channel": "pos",
  "lineItems": [
    {
      "productId": "PROD-12345",
      "sku": "SKU-VIT-C-1000",
      "title": "Vitamin C 1000mg",
      "quantity": 2,
      "price": 150,
      "discount": 0,
      "taxes": 45,
      "category": ["Vitamins", "Supplements"],
      "tags": ["immunity", "antioxidant"]
    },
    {
      "productId": "PROD-67890",
      "sku": "SKU-MOIST-50ML",
      "title": "Face Moisturizer 50ml",
      "quantity": 1,
      "price": 200,
      "discount": 0,
      "taxes": 30,
      "category": ["Skin Care", "Face Care"],
      "tags": ["moisturizer", "hydration"]
    }
  ]
}
The examples below show only the fields that change from Example 1. All other fields remain the same unless specified.

​
Example 2: Line Item Discount

Scenario: A specific item has a discount applied directly (e.g. item on sale). Tax is calculated on the full price and the discount is applied afterward.
ComponentCalculationValue
Vitamin C (2 × $150)$300
Face Moisturizer (1 × $200)$200
Subtotal$500
Vitamin C Tax$300 × 15%$45
Face Moisturizer Tax$200 × 15%$30
Total Tax$75
totalPrice500 + 75$575
Vitamin C Discount$50
totalDiscount$50
totalPaid575 - 50$525
{
  "orderId": "INV-2026-001235",
  "totalPrice": 575,
  "totalDiscount": 50,
  "totalTax": 75,
  "totalPaid": 525,
  "lineItems": [
    {
      "productId": "PROD-12345",
      "quantity": 2,
      "price": 150,
      "discount": 50,
      "taxes": 45
    },
    {
      "productId": "PROD-67890",
      "quantity": 1,
      "price": 200,
      "discount": 0,
      "taxes": 30
    }
  ]
}

​
Example 3: Order-Level Discount

Scenario: A commercial discount is applied to the entire order. Line items stay at full price.
ComponentCalculationValue
Vitamin C (2 × $150)$300
Face Moisturizer (1 × $200)$200
Subtotal$500
Vitamin C Tax$300 × 15%$45
Face Moisturizer Tax$200 × 15%$30
Total Tax$75
totalPrice500 + 75$575
Order-Level Discount15% off$75
totalDiscount$75
totalPaid575 - 75$500
{
  "orderId": "INV-2026-001236",
  "totalPrice": 575,
  "totalDiscount": 75,
  "totalTax": 75,
  "totalPaid": 500,
  "lineItems": [
    {
      "productId": "PROD-12345",
      "quantity": 2,
      "price": 150,
      "discount": 0,
      "taxes": 45
    },
    {
      "productId": "PROD-67890",
      "quantity": 1,
      "price": 200,
      "discount": 0,
      "taxes": 30
    }
  ]
}
Line items have discount: 0. The full discount is reflected at the order level via totalDiscount.

​
Example 4: Points Redemption

Scenario: Customer redeems Gameball points to pay part of the order via the hold/complete flow.
ComponentCalculationValue
totalPrice500 + 75$575
Points Redeemed$100
totalDiscount$100
totalPaid575 - 100$475
Step 1: Hold Points (before order) 
POST /api/v4.0/integrations/transactions/hold
Response returns holdReference: "HOLD-ABC123" Step 2: Complete Order with holdReference 
{
  "orderId": "INV-2026-001237",
  "totalPrice": 575,
  "totalDiscount": 100,
  "totalTax": 75,
  "totalPaid": 475,
  "redemption": {
    "pointsHoldReference": "HOLD-ABC123"
  }
}

​
Example 5: Coupon

Scenario: Customer applies a Gameball coupon code via the lock/complete flow.
ComponentCalculationValue
totalPrice500 + 75$575
Coupon Discount$50
totalDiscount$50
totalPaid575 - 50$525
Step 1: Lock Coupon (before order) 
POST /api/v4.0/integrations/coupons/lock
Response returns lockReference: "LOCK-XYZ789" Step 2: Complete Order with lockReference 
{
  "orderId": "INV-2026-001238",
  "totalPrice": 575,
  "totalDiscount": 50,
  "totalTax": 75,
  "totalPaid": 525,
  "redemption": {
    "couponsLockReference": "LOCK-XYZ789",
    "couponCodes": ["SUMMER50"]
  }
}

​
Example 6: Mixed — Points + Commercial Discount + Coupon

Scenario: Customer has a commercial discount, redeems Gameball points, and applies a coupon — all in one order.
ComponentCalculationValue
totalPrice500 + 75$575
Commercial Discount$25
Points Redeemed$50
Coupon Discount$25
totalDiscount25 + 50 + 25$100
totalPaid575 - 100$475
{
  "orderId": "INV-2026-001239",
  "totalPrice": 575,
  "totalDiscount": 100,
  "totalTax": 75,
  "totalPaid": 475,
  "redemption": {
    "pointsHoldReference": "HOLD-ABC123",
    "couponsLockReference": "LOCK-XYZ789",
    "couponCodes": ["LOYALTY25"]
  }
}
  • All discounts (commercial + points + coupon) are summed in totalDiscount
  • Gameball only uses totalPaid for earning points
  • The pointsHoldReference links the points redemption
  • The couponsLockReference links the coupon burn

​
Example 7: External Loyalty Program (e.g. Qitaf, Rajhi Points)

Scenario: Customer partially pays using a third-party loyalty program. This is treated as an order-level discount — no Gameball redemption is involved.
ComponentCalculationValue
totalPrice500 + 75$575
Qitaf Points Redeemed$100
totalDiscount$100
totalPaid575 - 100$475
{
  "orderId": "INV-2026-001240",
  "totalPrice": 575,
  "totalDiscount": 100,
  "totalTax": 75,
  "totalPaid": 475
}
Do not use redemption or the redemption object for external loyalty programs. Include the redeemed amount in totalDiscount only. Customer earns Gameball points on totalPaid (475).

​
Example 8: Discount Types (Free, % Off, Fixed)

Scenario: The discount is applied after tax is calculated, so the discount value covers both the product price and its tax portion. This is common when a POS reduces the line total directly (e.g. “make this item free” or “30% off the final price”). The key rule: tax is calculated on the full price, and the discount value must include the tax portion that’s being given away.

​
8a — Free Item (Free Product)

Vitamin C is given for free as part of a promo. The line value is **300+300 + 45 tax = 345∗∗,sothediscountmustcoverall345**, so the discount must cover all 345.
ComponentCalculationValue
Vitamin C (2 × $150)$300
Face Moisturizer (1 × $200)$200
Subtotal$500
Vitamin C Tax$300 × 15%$45
Face Moisturizer Tax$200 × 15%$30
Total Tax$75
totalPrice500 + 75$575
Vitamin C free item discountcovers price + tax$345
totalDiscount$345
totalPaid575 - 345$230
{
  "orderId": "INV-2026-001241",
  "totalPrice": 575,
  "totalDiscount": 345,
  "totalTax": 75,
  "totalPaid": 230,
  "lineItems": [
    {
      "productId": "PROD-12345",
      "quantity": 2,
      "price": 150,
      "discount": 345,
      "taxes": 45
    },
    {
      "productId": "PROD-67890",
      "quantity": 1,
      "price": 200,
      "discount": 0,
      "taxes": 30
    }
  ]
}
The customer paid nothing for Vitamin C, so no points are earned on that line. Points are still earned on the Face Moisturizer ($230).

​
8b — 30% Off (Percentage Discount)

Same items with a 30% off promo on Vitamin C. The discount applies to price + tax: 30% × (300+300 + 45) = $103.50.
ComponentCalculationValue
Vitamin C (2 × $150)$300
Face Moisturizer (1 × $200)$200
Subtotal$500
Vitamin C Tax$300 × 15%$45
Face Moisturizer Tax$200 × 15%$30
Total Tax$75
totalPrice500 + 75$575
Vitamin C 30% off discount30% × 345$103.50
totalDiscount$103.50
totalPaid575 - 103.50$471.50
{
  "orderId": "INV-2026-001242",
  "totalPrice": 575,
  "totalDiscount": 103.50,
  "totalTax": 75,
  "totalPaid": 471.50,
  "lineItems": [
    {
      "productId": "PROD-12345",
      "quantity": 2,
      "price": 150,
      "discount": 103.50,
      "taxes": 45
    },
    {
      "productId": "PROD-67890",
      "quantity": 1,
      "price": 200,
      "discount": 0,
      "taxes": 30
    }
  ]
}

​
8c — Fixed Discount ($20 Off)

A flat $20 off discount is applied to Vitamin C (e.g. a 20-currency coupon code). The discount value is sent as-is — it already represents the amount taken off the customer’s final bill, tax included.
ComponentCalculationValue
Vitamin C (2 × $150)$300
Face Moisturizer (1 × $200)$200
Subtotal$500
Vitamin C Tax$300 × 15%$45
Face Moisturizer Tax$200 × 15%$30
Total Tax$75
totalPrice500 + 75$575
Vitamin C fixed discount$20 off (tax-inclusive)$20
totalDiscount$20
totalPaid575 - 20$555
{
  "orderId": "INV-2026-001243",
  "totalPrice": 575,
  "totalDiscount": 20,
  "totalTax": 75,
  "totalPaid": 555,
  "lineItems": [
    {
      "productId": "PROD-12345",
      "quantity": 2,
      "price": 150,
      "discount": 20,
      "taxes": 45
    },
    {
      "productId": "PROD-67890",
      "quantity": 1,
      "price": 200,
      "discount": 0,
      "taxes": 30
    }
  ]
}
Whether the discount is a free product, a percentage, or a flat fixed amount, the rule is the same: the discount value already accounts for the tax portion — send it as-is. Gameball uses totalPaid to calculate points correctly in all three cases.

​
Summary Table

ExampleScenariototalPricetotalDiscounttotalPaidPoints Earned On
1Basic Order$575$0$575$575
2Line Item Discount$575$50$525$525
3Order-Level Discount$575$75$500$500
4Points Redemption$575$100$475$475
5Coupon$575$50$525$525
6Mixed (All)$575$100$475$475
7External Loyalty (Qitaf/Rajhi)$575$100$475$475
8aFree Item (Free Product)$575$345$230$230
8b30% Off (Percentage Discount)$575$103.50$471.50$471.50
8cFixed Discount ($20 Off)$575$20$555$555

​
Key Takeaway

Points are calculated based on totalPaid only.Gameball doesn’t need to know the breakdown of discounts. Just send:
  • totalPrice (items + taxes, before discounts)
  • totalDiscount (sum of ALL discounts including external loyalty)
  • totalPaid (what customer actually paid)