Skip to main content

​
Order Calculation Examples

This guide provides practical examples showing how to structure Order API payloads for common commerce scenarios including discounts, points redemption, and coupons. 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

Understanding how each field is calculated is essential for correct order tracking and points earning.

​
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
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)Line discount 50 + Points 100 → totalDiscount: 150
totalPaidWhat customer actually paid (totalPrice - totalDiscount)575 - 150 = totalPaid: 425
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 + pointsRedeemed + couponDiscount

totalPaid = totalPrice - totalDiscount

​
Line Item Attributes Reference

AttributeTypeDescription
productIdstringUnique product identifier
skustringStock keeping unit
titlestringProduct name
quantitynumberNumber of units
pricenumberUnit price
discountnumberTotal discount on this line item
taxesnumberTotal tax on this line item
weightnumberProduct weight
vendorstringVendor/supplier name
categoryarrayProduct categories
tagsarrayProduct tags
collectionarrayProduct collections
extraobjectCustom attributes (division, department, etc.)

​
Example 1: Basic Order with Line Items

Scenario: Customer purchases items with no discounts 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",
  "mobile": "+11234567890",
  "orderId": "INV-2026-001234",
  "orderDate": "2026-03-25T14:30:00Z",
  "totalPrice": 575,
  "totalDiscount": 0,
  "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,
      "weight": 0.1,
      "vendor": "Nature's Best",
      "category": ["Vitamins", "Supplements"],
      "tags": ["immunity", "antioxidant", "daily-health"],
      "collection": ["Best Sellers", "Health Essentials"],
      "extra": {
        "division": "Personal Care",
        "department": "Vitamins & Supplements",
        "categoryGroup": "Vitamins",
        "merchandiseCategory": "Vitamin C"
      }
    },
    {
      "productId": "PROD-67890",
      "sku": "SKU-MOIST-50ML",
      "title": "Face Moisturizer 50ml",
      "quantity": 1,
      "price": 200,
      "discount": 0,
      "taxes": 30,
      "weight": 0.15,
      "vendor": "CeraVe",
      "category": ["Skin Care", "Face Care"],
      "tags": ["moisturizer", "hydration", "daily-care"],
      "collection": ["Skin Care Essentials"],
      "extra": {
        "division": "Skin Care",
        "department": "Face Care",
        "categoryGroup": "Moisturizers",
        "merchandiseCategory": "Face Moisturizer"
      }
    }
  ],
  "merchant": {
    "uniqueId": "merchant-001",
    "name": "Your Store"
  },
  "branch": {
    "uniqueId": "branch-001",
    "name": "Main Branch"
  }
}
The examples below show only the fields that change from Example 1. All other fields (lineItems, merchant, branch) remain the same unless specified.

​
Example 2: Order with Line Item Discount

Scenario: A specific item has a discount (e.g., item on sale). Tax is calculated on the discounted amount.
ComponentCalculationValue
Vitamin C (2 × $150)$300
Face Moisturizer (1 × $200)$200
Subtotal$500
Vitamin C Discount$50
Vitamin C Tax(300−300 - 50) × 15%$37.50
Face Moisturizer Tax$200 × 15%$30
Total Tax$67.50
totalPrice500 + 67.50$567.50
totalDiscount$50
totalPaid567.50 - 50$517.50
{
  "orderId": "INV-2026-001235",
  "totalPrice": 567.5,
  "totalDiscount": 50,
  "totalPaid": 517.5,
  "lineItems": [
    {
      "productId": "PROD-12345",
      "quantity": 2,
      "price": 150,
      "discount": 50,
      "taxes": 37.5
    },
    {
      "productId": "PROD-67890",
      "quantity": 1,
      "price": 200,
      "discount": 0,
      "taxes": 30
    }
  ]
}

​
Example 3: Order with Order-Level Discount

Scenario: A commercial discount is applied to the entire order (not distributed to line items).
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,
  "totalPaid": 500
}
Line items have discount: 0. The 75 discount is at the order level only (totalDiscount).

​
Example 4: Order with Points Redemption

Scenario: Customer redeems points to pay part of the order.
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
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,
  "totalPaid": 475,
  "redemption": {
    "pointsHoldReference": "HOLD-ABC123"
  }
}
Points redeemed value (100) is included in totalDiscount. Customer earns points only on totalPaid (475).

​
Example 5: Order with Coupon

Scenario: Customer applies a coupon code.
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
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,
  "totalPaid": 525,
  "redemption": {
    "couponsLockReference": "LOCK-XYZ789",
    "couponCodes": ["SUMMER50"]
  }
}

​
Example 6: Mixed - Points + Discount + Coupon

Scenario: Customer has commercial discount, redeems points, AND uses a coupon.
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
Commercial Discount$25
Points Redeemed$50
Coupon Discount$25
totalDiscount25 + 50 + 25$100
totalPaid575 - 100$475
{
  "orderId": "INV-2026-001239",
  "totalPrice": 575,
  "totalDiscount": 100,
  "totalPaid": 475,
  "redemption": {
    "pointsHoldReference": "HOLD-ABC123",
    "couponsLockReference": "LOCK-XYZ789",
    "couponCodes": ["LOYALTY25"]
  }
}
Key Points:
  • 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: Order Level Discount + Points Redemption

Scenario: Customer has a commercial discount on the order AND redeems points (no coupon).
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
Commercial Discount$50
Points Redeemed$75
totalDiscount50 + 75$125
totalPaid575 - 125$450
{
  "orderId": "INV-2026-001240",
  "totalPrice": 575,
  "totalDiscount": 125,
  "totalPaid": 450,
  "redemption": {
    "pointsHoldReference": "HOLD-DEF456"
  }
}
Key Points:
  • Commercial discount (50) + Points redeemed (75) = Total Discount (125)
  • Only pointsHoldReference in redemption object (no coupon)
  • Customer earns points on totalPaid (450)

​
Summary Table

ExampleScenarioSubtotalTaxtotalPricetotalDiscounttotalPaidPoints Earned On
1Basic Order$500$75$575$0$575$575
2Line Item Discount$500$67.50$567.50$50$517.50$517.50
3Order Level Discount$500$75$575$75$500$500
4Points Redemption$500$75$575$100$475$475
5Coupon$500$75$575$50$525$525
6Mixed (All)$500$75$575$100$475$475
7Order Discount + Points$500$75$575$125$450$450

​
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)
  • totalPaid (what customer actually paid)