Gameball Developers Guide
v3.0
Gameball WebsiteHelp CenterBlog
Search
⌃K
Links

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

https://api.gameball.co/api/v3.0/integrations/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 player 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

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 player in your database.
mobile
string
No
Player's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Player'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
The actual paid amount to the store. (Based on this amount, the player will be rewarded. Also, According to the Cashback Configuration). Must be positive.
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
A list of line item objects, each containing information about an item in the order.
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 player 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
Merchant object describes the merchant itself.

lineItems Object

Attribute
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

Attribute
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 player doesn't exist on Gameball before sending the Orders API call, the player will be created automatically on Gameball.

Sample Request Body

{
"playerUniqueId":"player456",
"orderId": "6253e03b",
"orderDate":"2019-09-21T16:53:28.190Z",
"totalPrice": "100",
"totalPaid": "90",
"totalDiscount": "0",
"totalShipping": "0",
"totalTax": "0",
"lineItems":[
{
"productId":"197765",
"tag": ["VIP"],
"quantity": 2,
"category": [
"natural",
"cosmetics"
],
"weight": "20",
"vendor": "nike",
"collection": ["14313", "4343"],
},
{
"productId":"875511",
"title": "XPS-15s",
"category": [
"electronics"
],
"vendor": "Dell"
}
],
"discountCodes": [
"AU7X-8Q7L",
"BY3V-22GK"
],
"extra": {
"paymentMethod": "credit card",
"billingAddress": "Alabama"
},
"redeemedAmount": 20,
"holdReference": null,
"guest": false
}

Response

Parameter
Type
Description
playerUniqueId
string
Unique identifier for the player in your database.
redeemedPoints
integer
The number of points redeemed by the player while placing his order
rewardedPoints
integer
The number of points rewarded to the player for the paid amount. (Based on your Cashback configuration)
lineItems
array
Array of lineItem response objects, for each lineItem response object, the productId, quantity, points and score are provided.

lineItem response object

Attribute
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 players to level up.
quantity
integer
The number of items purchased of this line item.

Sample Response Body

{
"playerUniqueId": "player456",
"redeemedPoints": null,
"rewardedPoints": 1000,
"lineItems": [
{
"productId": "875511",
"quantity": "1",
"decimalPoints": 400.0,
"points": 400,
"score": 0
},
{
"productId": "197765",
"quantity": "2",
"decimalPoints": 300.0,
"points": 300,
"score": 0
}
]
}

Usage Example

cURL
Ruby
PHP
Python
.NET
curl -X POST -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
-H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' --data-raw '{
"playerUniqueId":"player456",
"orderId": "6253e03b",
"orderDate":"2019-09-21T16:53:28.190Z",
"totalPrice": "100",
"totalPaid": "90",
"totalDiscount": "0",
"totalShipping": "0",
"totalTax": "0",
"lineItems":[
{
"productId":"197765",
"tag": ["VIP"],
"quantity": 2,
"category": [
"natural",
"cosmetics"
],
"weight": "20",
"vendor": "nike",
"collection": ["14313", "4343"],
},
{
"productId":"875511",
"title": "XPS-15s",
"category": [
"electronics"
],
"vendor": "Dell"
}
]
"discountCodes": [
"AU7X-8Q7L",
"BY3V-22GK"
],
"extra": {
"paymentMethod": "credit card",
"billingAddress": "Alabama"
},
"redeemedAmount": 20,
"holdReference": null,
"guest": false
}' -v -i 'https://api.gameball.co/api/v3.0/integrations/order'
Gameball::Order.place_order({
playerUniqueId:"player456",
orderId: "6253e03b",
totalPrice: "100",
totalPaid: "90",
totalDiscount: "0",
totalShipping: "0",
totalTax: "0",
lineItems:[
{
productId:"197765",
tag: ["VIP"],
category: [
"natural",
"cosmetics"
],
weight: "20",
vendor: "nike",
collection: ["14313", "4343"],
},
{
productId:"875511",
title: "XPS-15s",
category: [
"electronics"
],
vendor: "Dell"
}
],
discountCodes: [
"AU7X-8Q7L",
"BY3V-22GK"
],
extra: {
paymentMethod: "credit card",
billingAddress: "Alabama"
},
redeemedAmount: 20,
holdReference: nil,
guest: false
})
$orderRequest = \Gameball\Models\OrderRequest::factory("player456",
"6253e03b",100, 90, 0, 0);
$orderRequest->addLineItem(new \Gameball\Models\LineItem("197765",null,["VIP"],["natural","cosmetics"],
"20",null, null,"nike",["14313", "4343"]));
$orderRequest->addLineItem(new \Gameball\Models\LineItem("875511","XPS-15s",null,["electronics"],
null,null, null,"Dell",null));
​
$response = $gameball->order->sendOrder($orderRequest);
line_item_1 = gameball.lineItem(
product_id = "197765",
category = ["natural","cosmetics"],
collection = ["14313", "4343"],
tags = ["VIP"],
weight = "20",
vendor = "nike",
quantity = 1
)
​
line_item_2 = gameball.lineItem(
product_id = "875511",
title: "XPS-15s",
category: [
"electronics"
],
vendor: "Dell"
quantity = 1
)
​
order = gameball.orderObject("player456",
order_id="6253e03b",
total_price=100,total_paid=90,
discount_codes= [
"AU7X-8Q7L",
"BY3V-22GK"
],
extra= {
paymentMethod: "credit card",
billingAddress: "Alabama"
},
redeemed_amount= 20)
​
order.add_lineItem(line_item_1)
order.add_lineItem(line_item_2)
order_response = gameball.send_order(order)
var lineItem1 = new Lineitem()
{
ProductId = "197765",
Category = new string[] {"natural", "cosmetics"},
Weight = 20,
Vendor = "nike",
Quantity = 1,
Collection = new string[] {"14313", "4343"},
};
​
var lineItem2 = new Lineitem()
{
ProductId = "875511",
Title= "XPS-15s",
Category = new string[] {"electronics"},
Vendor = "Dell",
Quantity = 1
};
​
var lineItems = new Lineitem[] {
lineItem1, lineItem2
};
​
var request = new OrderRequest() {
PlayerUniqueId = "player456",
OrderId = "6253e03b",
TotalPaid = 100,
TotalPrice = 90,
TotalDiscount = 0,
TotalShipping = 0,
TotalTax = 0,
LineItems = lineItems
};
​
var response = Gameball.Order(request);

POST - Calculate Order Cashback

https://api.gameball.co/api/v3.0/integrations/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 player in your database
(Note :While the playerUniqueId is not mandatory, its inclusion can have a significant impact on the response tailored to that unique player. Consider including it to enable personalized points and level configurations.)
mobile
string
No
Player's unique mobile number. (Sent in case your account supports channel merging)
email
string
No
Player's unique email. (Sent in case your account supports channel merging)
totalPaid
number
Yes
The actual paid amount to the store. (Based on this amount, the player will be rewarded. Also, According to the Cashback Configuration). Must be positive.
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
A list of lineItem objects, each containing information about an item in the order.
merchant
object
No
Merchant object describes the merchant itself.

lineItems Object

Attribute
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

Attribute
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 player doesn't exist on Gameball before sending the Orders API call, the player will be created automatically on Gameball.

Sample Request Body

{
"playerUniqueId":"player456",
"totalPaid":300,
"totalPrice":180,
"totalDiscount":30,
"totalShipping":30,
"totalTax":0,
"lineItems":[
{
"productId":"875511",
"price":150,
"quantity":2,
"collection":[
"14313",
"4343"
],
"taxes":0,
"discount":30
}
]
}

Response

Parameter
Type
Description
totalPoints
integer
The total rewarded points by the order
totalScore
integer
The total rewarded score by the order.
lineItems
array
Array of lineItem response objects, for each lineItem response object, the productId, quantity, points and score are provided.

lineItem response object

Attribute
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

{
"totalPoints": 300,
"totalScore": 0,
"lineItems": [
{
"productId": "875511",
"quantity": 2,
"decimalPoints": 135.0,
"points": 135,
"score": 0
},
{
"productId": "Shipping",
"quantity": 1,
"decimalPoints": 30.0,
"points": 30,
"score": 0
}
]
}

Usage Example

cURL
curl --location --request POST 'https://api.gameball.co/api/v3.0/integrations/order/cashback' \
--header 'apiKey: 47369abf791640aaa3c319ce07a61727' \
--header 'Content-Type: application/json' \
--data-raw '{
"playerUniqueId": "player456",
"totalPaid": 300,
"totalPrice": 180,
"totalDiscount": 30,
"totalShipping": 30,
"totalTax": 0,
"lineItems": [
{
"productId": "875511",
"price": 150,
"quantity": 2,
"collection": [
"14313",
"4343"
],
"taxes": 0,
"discount": 30
}
]
}'
Previous
Transactions
Next
Leaderboard 👑
Last modified 2d ago