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.

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

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'

Ruby

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
})

PHP

$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);

Python

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)

.NET

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

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
        }
    ]
}

Ruby

Gameball::Order.order_cashback({
  playerUniqueId:"player456",   
  totalPrice: "100",
  totalPaid: "90",
  totalDiscount: "0",
  totalShipping: "0",
  totalTax: "0", 
  lineItems:[
    {
      productId:"875511",
      price: 150,
      quantity: 2,
      collection: ["14313", "4343"],
       taxes: 0,
      discount: 30
    }
  ]
})

PHP

$cashbackRequest = \Gameball\Models\CashbackRequest::factory("player456",
    100, 90, 0, 0);
$cashbackRequest->addLineItem(new \Gameball\Models\LineItem("875511","150","2",
    ["14313", "4343"],"0","30"));

$response = $gameball->order->calculateOrderCashback($cashbackRequest);

Python

line_item_1 = gameball.lineItem(
         product_id = "875511",
         collection = ["14313", "4343"], 
         discount= 30,
         taxes= 0,
         price= 150, 
         quantity = 2
     )

cashback = gameball.cashbackObject("player456",
         total_price=100,total_paid=90,
         total_discount=0,
         total_shipping=0,
         total_tax=0
     )

cashback.add_lineItem(line_item_1)
cashback_response = gameball.calculate_cashback(order)

.NET

var lineItem1 = new Lineitem() 
	{
	  ProductId = "875511",  
	  Price = 150,
	  Quantity = 2,
	  Collection = new string[] {"14313", "4343"},
	  Taxes= 0,
	  Discount= 30
	};

var lineItems = new Lineitem[] {
	lineItem1
};

var request = new CashbackRequest() {
	PlayerUniqueId = "player456",
	TotalPaid = 100,
	TotalPrice = 90,
	TotalDiscount = 0,
	TotalShipping = 0,
	TotalTax = 0, 
	LineItems = lineItems
};

var response = Gameball.Cashback(request);