Orders

Track Order

Changed on

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 both 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.

post/api/v4.0/integrations/orders

Request

  • Base URL: https://api.gameball.co
  • URL: https://api.gameball.co/api/v4.0/integrations/orders
  • Auth: API key in header apikey and API key in header secretkey

Request body

customerIdstring 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.

emailstring

Customer's email address. Note: This is required if your account uses email-based channel merging.

mobilestring

Customer's mobile number. Note: This is required if your account uses mobile-based channel merging.

orderIdstring required

Unique identifier for the order on your system. This ID is case-sensitive.

orderDatestring date-time required

Timestamp of when the order was placed. Must be in UTC (ISO 8601 format), e.g. 2024-10-16T08:13:29.290Z.

totalPaidnumber 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.

totalPricenumber

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.

totalDiscountnumber

Total discount applied to the order.

totalShippingnumber

Total shipping cost associated with the order.

totalTaxnumber

Total tax amount for the order.

extraobject

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.

guestboolean

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'mobile' | 'pos' | 'web' | 'callcenter'

The channel through which the order was placed helps track the origin of the order, particularly useful for systems that support multiple sales or communication channels. By identifying the channel, you can gain valuable insights into customer behavior, optimize channel-specific strategies, and ensure efficient handling of orders across platforms. Possible values: mobile - The order was placed through your mobile application. pos - The order was placed in person using a Point of Sale (POS) system, such as at a physical store or outlet. web - The order was placed through your website. callcenter - The order was placed over the phone by contacting a customer service representative or a call center.

cartIdstring

Identifier for the shopping cart associated with the order.

Example request

{
  "customerId": "cust_123456789",
  "email": "john.doe@example.com",
  "mobile": "+1234567890",
  "orderId": "ORD12345",
  "orderDate": "2024-10-16T08:13:29.290Z",
  "totalPaid": 250.75,
  "totalPrice": 300,
  "totalDiscount": 50,
  "totalShipping": 10,
  "totalTax": 15,
  "lineItems": [
    {
      "productId": "PROD98765",
      "quantity": 2,
      "price": 100,
      "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"
    }
  },
  "channel": "pos",
  "cartId": "CART98765",
  "cashbackConfigurations": {
    "returnWindow": 7
  }
}

Response

Order tracked successfully

customerIdstring

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.

redeemedPointsnumber

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.

rewardedPointsnumber

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.

Example response

{
  "customerId": "cust_123456789",
  "redeemedPoints": 1000,
  "rewardedPoints": 101,
  "lineItems": [
    {
      "productId": "PROD98765",
      "quantity": 2,
      "decimalPoints": 91.25,
      "points": 91
    }
  ]
}

Changes

  • 262228c13429Revision changes
    • info

      the endpoint scheme security apiKey AND secretKey was added to the API

    • info

      the endpoint scheme security apiKey was removed from the API

    • info

      the endpoint scheme security secretKey was removed from the API

  • 788718651767Revision changes
    • info

      removed the non-success response with the status