Order Tracking

Create orders in Gameball to award points for customer purchases. This API is used to track orders and reward customers for their completed purchases.

Available APIs

• Track Order

---

POST - Track Order

https://api.gameball.co/api/v4/integrations/orders

The API call is used to track a new order and is specifically designed for e-commerce solutions. It helps capture essential order details, enabling better tracking of customer purchases and order management.

Security: Requires apikey and secretkey headers.

Channel Merging Available If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball's channel merging feature helps unify customer profiles. By including the customer’s mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.For more information, head to the Channel Merging Guide.

Request

Body

application/json

customerId string Required Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer.

---

email string Optional Customer's email address.

Note: This is required if your account uses email-based channel merging.

---

mobile string Optional Customer's mobile number.

Note: This is required if your account uses mobile-based channel merging.

---

orderId string Required Unique identifier for the order on your system.

---

totalPaid float Required The actual amount paid by the customer for the order, accounting for any discounts or coupons applied. Unlike totalPrice, which reflects the original cost of the order, totalPaid represents the final amount the customer paid at checkout after all adjustments. This value is used for reward calculations in Gameball to determine the points or benefits earned from the order.

Example: A customer purchases items worth $120, including taxes and shipping. If a $20 coupon is applied, the totalPaid becomes $100, reflecting the discounted amount the customer paid. This is the value used to calculate any points or rewards earned from the order.

---

totalPrice float Optional The total cost of the order, including all item prices, shipping, taxes, and tips. This value does not account for any discounts or coupons applied and is not used for calculations in Gameball; it is solely saved as historical data linked to the order. Must be a positive value.

Example: A customer purchases items worth $120, including taxes and shipping. Even if a $20 coupon is applied, the totalPrice remains $120 as it represents the original cost of the order before any discounts are applied.

---

orderDate datetime Optional Timestamp of when the order was placed.

---

totalDiscount float Optional Total discount applied to the order.

---

totalShipping float Optional Total shipping cost associated with the order.

---

totalTax float Optional Total tax amount for the order.

---

lineItems array Optional An array containing details about each product in the order. If not provided, the calculation will only consider the total order values.

lineItems object

productId string Optional Unique identifier for the product or service being purchased.

---

quantity float Optional Number of units purchased for this product or service.

---

price float Optional TThe original price of a single product before any tax or discount is applied. This reflects the cost of one unit of the item, not the total for multiple quantities in an order.

Example: If the original price of a product is $50 and a customer buys two units, the price for each item would still be recorded as $50, regardless of quantity.

---

sku string Optional Stock Keeping Unit (SKU) for the product.

---

tags array Optional Tags associated with the product for categorization or promotional purposes.

---

category array Optional Product category, such as fashion or electronics. It can include one or multiple categories. Example: ["natural", "cosmetics"]

---

weight float Optional Weight of the product.

---

vendor string Optional Vendor or manufacturer of the product.

---

collection array Optional Collection ID(s) to which the product belongs. It can include one or multiple collections. Example: ["14313", "4343"]

---

title string Optional Product title or name.

---

taxes float Optional The total amount of taxes applied to the line item, expressed in the shop's currency. This amount must be positive and reflects the total taxes based on the quantity of the item.

---

discount float Optional The total discount applied to this line item, expressed as a positive value. This amount should reflect the total discounts based on the quantity of the item.

---

extra object Optional Key-value pairs containing any extra information about the product, such as size, color, or other custom attributes. The values must be of type string or number.

---

redemption object Optional Redemption details for the order, including points held for redemption.

redemption object

pointsHoldReference string Optional Reference from the Hold Points API for redeeming held points. For more details on how hold references are generated and utilized, refer to the Transactions section.

---

couponsLockReference string Optional The lock reference for the coupon is a unique identifier used to "lock" a coupon for a specific customer or order. This prevents the coupon from being used by others or on multiple transactions. For more details on how to generate and use lock references,refer to the Coupons section.

Example: If you lock a coupon for a specific transaction, the lockReference could look like "lockReference": "abc123def456".

{
  "lockReference": "abc123def456"
}

---

couponCodes array Optional

A list of coupon codes that were applied to the order. Each code in the array represents a different discount or promotional coupon used during the checkout process.

Example: If a customer applied two coupon codes, one for a 10% discount and another for free shipping, the couponCodes array might look like this:

{
  "couponCodes": ["DISCOUNT10", "FREESHIP2024"]
}

---

extra object Optional Key-value pairs containing any extra information about the order. The values must be of type string or number.

Example : If your business offers gift options, you might want to include a personalized gift message with the order. Additionally, specific delivery instructions can be recorded to ensure smooth delivery and provide a personalized experience.

{
  "giftMessage": "Happy Birthday! Enjoy your gift!",
  "deliveryInstructions": "Leave the package at the front door if no one is home.",
}

---

merchant object Optional This object contains details about the specific merchant involved in the transaction, which is particularly important for businesses managing multiple merchants or branches under the same Gameball account. This object can provide identifying information about both the main merchant and any associated branch where the transaction took place.

merchant object

uniqueId string Optional Unique identifier for the merchant.

---

name string Optional Name of the merchant.

---

branch.uniqueId string Required Unique identifier for the branch where the order took place.

---

branch.name string Optional Name of the branch where the order took place.

---

guest boolean Optional Indicates whether the customer is a guest (not signed up). Set this to true for guest users; otherwise, they are treated as registered customers by default.

---

channel string Optional Channel through which the order was placed (e.g., online, in-store).

---

cartId string Optional Identifier for the shopping cart associated with the order.

---

Sample Request

{
  "customerId": "cust_123456789",
  "email": "[e-mail]",
  "mobile": "[phone]",
  "orderId": "ORD12345",
  "orderDate": "2024-10-16T08:13:29.290Z",
  "totalPaid": 250.75,
  "totalPrice": 300,
  "totalDiscount": 50,
  "totalShipping": 10,
  "totalTax": 15,
  "lineItems": [
    {
      "price": 100,
      "quantity": 2,
      "productId": "PROD98765",
      "sku": "SKU98765",
      "tags": [
        "electronics",
        "smartphone"
      ],
      "category": [
        "mobile phones"
      ],
      "weight": 0.5,
      "vendor": "TechVendor",
      "collection": [
        "latest gadgets"
      ],
      "title": "Smartphone XYZ",
      "taxes": 7.5,
      "discount": 25,
      "extra": {
        "subClass": "SUBCLASS123"
      }
    }
  ],
  "redemption": {
    "pointsHoldReference": "HOLD123",
    "couponsLockReference": "LOCK123",
    "couponCodes": [
      "DISCOUNT10"
    ]
  },
  "extra": {
    "paymentMethod": "CREDIT CARD"
  },
  "merchant": {
    "uniqueId": "MERCH001",
    "name": "TechGadgetStore",
    "branch": {
      "uniqueId": "BRANCH001",
      "name": "Downtown Branch"
    }
  },
  "guest": false,
  "channel": "online",
  "cartId": "CART98765"
}

---

Response

application/json

customerId string Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer.

---

redeemedPoints number Points redeemed by the customer for this order, if applicable.

Example:If a customer has accumulated 500 points and decides to redeem 100 points for a discount on their current order, the redeemedPoints value for that transaction will be 100. This helps track how many points were used in the transaction and what benefits were applied to the order based on the customer's redeemed points.

---

rewardedPoints number The total number of points rewarded to the customer for making this order. These points are typically awarded based on your configured cashback rewards.

Example: If the store rewards 10 points for every $1 spent, and a customer places an order worth $50, the rewardedPoints for this order would be 500 points.

---

lineItems array Details about each product or service in the order, including points rewarded.

lineItems object

productId string Unique identifier for the product or service.

---

quantity number Number of units purchased for this product or service.

---

decimalPoints number Fractional points rewarded for this line item.

---

points number Any points rewarded for this line item.

---

score number Any score awarded for the line item, if applicable.

---

Sample Response

{
    "customerId": "cust_123456789",
    "redeemedPoints": 1000,
    "rewardedPoints": 101,
    "lineItems": [
        {
            "productId": "PROD98765",
            "quantity": 2,
            "decimalPoints": 91.25,
            "points": 91,
            "score": 0
        },
        {
            "productId": "Shipping",
            "quantity": 1,
            "decimalPoints": 10.0,
            "points": 10,
            "score": 0
        }
    ]
}
           

---