Order
The order endpoints are used to track a new order. They are designed specifically for E-Commerce Solutions.
Available Endpoints
Type
Description
Endpoint
POST
/integrations/order
POST
/integrations/order/cashback
POST - Order
After successfully placing a new order on your system, this endpoint can be used to track order details, optionally redeem points, and finally rewarding the customer for the placed order.
This endpoint performs multiple operations internally including sending an event, reward wallet points, redeem wallet points as per your configured programs. It offers a hassle-free single point of integration for e-commerce cases.
Order endpoint internally triggers a "place_order" event, so no need to manually send such event to Gameball after placing an order
For more information about tracking orders and cashback reward, check checkout integration example tutorial
mobile
or email
should be sent along with the playerUniqueId
in case (only if) your account supports channel merging.
In cases where channel merging is supported, you have the flexibility to identify users by their mobile number or email. For accounts utilizing separate systems for online and offline channels, it's advisable to consider changing the customer's unique ID to either their mobile number or email address for enhanced efficiency.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
secretKey
string
Yes
Client Secret Key
Body
Attribute
Type
Required
Description
playerUniqueId
string
Yes
Unique identifier for the customer in your database.
mobile
string
No
Customer's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Customer's unique email. (Sent in case your account supports channel merging)
orderId
string
Yes
Unique order ID which identifies the underlying order in your system, e.g. order number, invoice number. It will be used for reversing any reward or redemption transaction on Gameball.
orderDate
string
Yes
The date this order was placed, as an ISO8601 timestamp. Defaults to now if not provided.
Example:"2019-09-21T16:53:28.190Z"
totalPaid
number
Yes
totalPrice
number
No
The sum of all order items' prices, including discounts, shipping, taxes, and tips. (Note: totalPaid
is part of the totalPrice
). Must be positive.
Example:
"totalPaid": 22,
"totalPrice": 30
totalShipping
number
No
The total shipping price of the order. Must be positive.
totalTax
number
No
The sum of all the taxes applied to the order in the shop currency. Must be positive.
totalDiscount
number
No
Total discount applied on this order. Must be positive.
lineItems
array
No
discountCodes
array
No
An array of discount codes.
Example:["AU7X-8Q7L", "BY3V-22GK"]
extra
object
No
Key value pair(s) of any extra information about the order. The key values must be of type string or number
Example:
"extra": {
"paymentMethod": "credit card"
}
redeemedAmount
number
No
Monetary value of the redeemed points to be used by that customer while placing his order.
Note: If this field is set, then the holdReference
value should be null. Also, both fields could be null.
holdReference
string
No
Hold reference ID is received after calling Hold Points API. This is used in case you want to use already held points
Note: If this field is set, then the redeemedAmount
value should be null. Also, both fields could be null.
guest
boolean
No
A boolean value indicating if the customer who placed this order is a guest. The default is false.
merchant
object
No
lineItems
Object
lineItems
ObjectAttribute
Type
Required
Description
productId
string
No
The ID of the product that the line item belongs to
sku
string
No
The item's SKU (stock keeping unit).
title
string
No
The title of the product.
category
array
No
Product category (fashion, electronics.. etc). It can be one category or multiple categories.
Example:["natural","cosmetics"]
collection
array
No
Collection ID(s) to which the product belongs. It can be one collection or multiple collections. This will be also based on the available collections in your store.
Example:["14313","4343"]
tags
array
No
Tag(s) attached to the item in the order.
Example:["VIP", "Elite"]
weight
number
No
Item weight. Must be positive.
vendor
string
No
The name of the item's supplier.
Example:"nike"
quantity
number
No
Number of items purchased of this line item. Must be positive.
price
number
Yes *
The original price of the product before adding tax or discount. Note that: it should reflect the price of a single product ignoring quantity
taxes
number
Yes *
The sum of all the taxes applied to the line item in the shop currency. Must be positive. Note that: It should reflect total taxes for line item considering quantity
discount
number
Yes *
Total discount applied on this line item. Must be positive. Note that: This value should reflect total discounts for line item considering quantity
The (*) in the required column denotes that this value is required only if you wish to use the Custom Cashback configurations.
merchant
object
merchant
objectAttribute
Type
Description
uniqueId
string
Merchant unique id or code
name
string
Merchant name
branch
object
Optional branch information
branch.uniqueId
string
Branch unique id or code
branch.name
string
Branch name
In case the customer doesn't exist on Gameball before sending the Orders API call, the customer will be created automatically on Gameball.
Sample Request Body
Response
Parameter
Type
Description
playerUniqueId
string
Unique identifier for the customer in your database.
redeemedPoints
integer
The number of points redeemed by the customer while placing his order
rewardedPoints
integer
lineItems
array
lineItem
response object
lineItem
response objectAttribute
Type
Description
productId
string
The ID of the product that the line item belongs to.
points
integer
The rewarded points for one product only and can be redeemed later with monetary value for discounts or free items.
decimalPoints
float
The rewarded points for one product only as a decimal number.
score
integer
The rewarded score for one product only and it can allow customers to advance to the next VIP tier.
quantity
integer
The number of items purchased of this line item.
Sample Response Body
Usage Example
POST - Calculate Order Cashback
This API is used to calculate the order cashback points to be rewarded based on your cashback config. It can be also used to show the cashback points to be rewarded for a single product by providing a single line item in the request.
mobile
or email
should be sent along with the playerUniqueId
in case (only if) your account supports channel merging.
Request
Header
Attribute
Type
Required
Description
APIKey
string
Yes
Client API key
Body
Attribute
Type
Required
Description
playerUniqueId
string
No
Unique identifier for the customer in your database
(Note :While the playerUniqueId
is not mandatory, its inclusion can have a significant impact on the response tailored to that unique customer. Consider including it to enable personalized points and VIP tier configurations.)
mobile
string
No
Customer's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Customer's unique email. (Sent in case your account supports channel merging)
totalPaid
number
Yes
totalPrice
number
No
The sum of all order items' prices, including discounts, shipping, taxes, and tips. (Note: totalPaid
is part of the totalPrice
). Must be positive.
Example:
"totalPaid": 22,
"totalPrice": 30
totalShipping
number
No
The total shipping price of the order. Must be positive.
totalTax
number
No
The sum of all the taxes applied to the order in the shop currency. Must be positive.
totalDiscount
number
No
Total discount applied on this order. Must be positive.
lineItems
array
No
merchant
object
No
lineItems
Object
lineItems
ObjectAttribute
Type
Required
Description
productId
string
No
The ID of the product that the line item belongs to
collection
array
No
Collection ID(s) to which the product belongs. It can be one collection or multiple collections. This will be also based on the available collections in your store.
Example:["14313","4343"]
quantity
number
No
Number of items purchased of this line item. Must be positive.
price
number
Yes *
The original price of the product before adding tax or discount. Note that: it should reflect the price of a single product ignoring quantity
taxes
number
Yes *
The sum of all the taxes applied to the line item in the shop currency. Must be positive. Note that: It should reflect total taxes for line item considering quantity
discount
number
Yes *
Total discount applied on this line item. Must be positive. Note that: This value should reflect total discounts for line item considering quantity
The (*) in the required column denotes that this value is required only if you wish to use the Custom Cashback configurations.
merchant
object
merchant
objectAttribute
Type
Description
uniqueId
string
Merchant unique id or code
name
string
Merchant name
branch
object
Optional branch information
branch.uniqueId
string
Branch unique id or code
branch.name
string
Branch name
Sample Request Body
Response
Parameter
Type
Description
totalPoints
integer
The total rewarded points by the order
totalScore
integer
The total rewarded score by the order.
lineItems
array
lineItem
response object
lineItem
response objectAttribute
Type
Description
productId
string
The ID of the product that the line item belongs to.
points
integer
The rewarded points for a one product only
decimalPoints
float
The rewarded points for a one product only as a decimal number
score
integer
The rewarded score for a one product only
quantity
integer
The number of items purchased of this line item.
Sample Response
Usage Example
Last updated