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
​Send Order​
/integrations/order
POST
​Calculate Order Cashback​
/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.
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 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
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 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 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.
Sample Response Body
{
    "playerUniqueId": "player456",
    "redeemedPoints": null,
    "rewardedPoints": 1000,
     "lineItems": [
        {
            "productId": "875511",
            "quantity": "1",
            "points": 400,
            "score": 0
        },
        {
            "productId": "197765",
            "quantity": "2",
            "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
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
A list of line item 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
score
integer
The rewarded score for a one product only
quantity
integer
The number of items purchased of this line item.
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
        }
    ]
}'

Transactions

Leaderboard 👑

Last modified 10d ago

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

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

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

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.

Order

Available Endpoints

POST - Order

Request

Header

Body

`lineItems` Object

`merchant` object

Sample Request Body

Response

`lineItem` response object

Sample Response Body

Usage Example

POST - Calculate Order Cashback

Request

Header

Body

`lineItems` Object

`merchant` object

Sample Request Body

Response

`lineItem` response object

Usage Example

Type	Description	Endpoint
POST	Send Order	/integrations/order
POST	Calculate Order Cashback	/integrations/order/cashback

Attribute	Type	Required	Description
`APIKey`	string	Yes	Client API key
`secretKey`	string	Yes	Client Secret Key