Order
The order endpoints are used to track a new order. They are designed specifically for E-Commerce Solutions.
Type | Description | Endpoint |
POST | /integrations/order | |
POST | /integrations/order/cashback |
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.Attribute | Type | Required | Description |
APIKey | string | Yes | Client API key |
secretKey | string | Yes | Client Secret Key |
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 | Yes | 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 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 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 |
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.
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.
{
"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
}
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. |
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 |
score | integer | The rewarded score for a one product only |
quantity | integer | The number of items purchased of this line item. |
{
"playerUniqueId": "player456",
"redeemedPoints": null,
"rewardedPoints": 1000,
"lineItems": [
{
"productId": "875511",
"quantity": "1",
"points": 400,
"score": 0
},
{
"productId": "197765",
"quantity": "2",
"points": 300,
"score": 0
}
]
}
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);
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.Attribute | Type | Required | Description |
APIKey | string | Yes | Client API key |
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) |
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 | Yes | 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 |
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.
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.
{
"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
}
]
}
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. |
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 |
score | integer | The rewarded score for a one product only |
quantity | integer | The number of items purchased of this line item. |
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
}
]
}'
Last modified 10d ago