Checkout Integration Example

What you will learn in this tutorial:
In this tutorial, we will be discussing how to integrate Gameball into your checkout for a better Ecommerce experience. Using the Orders API - specifically built for e-commerce - will enable Gameball to track order details, reward cashback, or redeem points upon purchasing for your customers.
We will walk you through different use cases showing various scenarios where you can integrate Gameball within your checkout experience using the Orders API.

The use cases describe how you can make use of the Orders Endpoint in different ways, whether redeeming points while ordering, or rewarding players for the paid amount, or just tracking placing the order event.
By the end of this tutorial, using the Orders API endpoint you should be able to:
Track your player’s order event and the order details.
Redeem points from your player before heading to checkout, or along with the order details being sent after the successful payment.
The use cases covered in this tutorial are:
1.​Tracking Player’s Orders​
2.​Player redeeming points while placing an order​
3.​Redeem points using hold​
So let’s dive into each use case.
In this guide, we will be showing the usage of the Order API with an example checkout page
Tracking Player Order Details
Let’s start by just placing an Order. You may find it useful to track your customers’ orders once they are complete and paid, to be able to assess and evaluate certain details. For instance, you may have some challenges configured to be completed/achieved once certain products are purchased. Once the Order API is called, it internally triggers a place_order event including all the order’s data as metadata.
Take the example below, where your customer placed an order with a "Hoxton Bag" and a "Brixton Jacket" as shown in the image below. After the order is successfully placed and paid you will be sending to Gameball the order data via Order API as follows 

To build the Order API request payload, you need to supply three main blocks each of which holds Order information from a different perspective.
Initially, you need to set the order identifiers which are:
playerUniqueId: the unique identifier of the player who made the order
OrderId: the unique order ID which identifies the order transaction in your system, e.g. order number, invoice number. It will be used for reversing any reward or redemption transaction on Gameball. 
orderDate: similar to what is set on your system, as below
1
{ 
2
  ...
3
  "playerUniqueId": "player456",
4
  "orderId": "6253e03b",
5
  "orderDate": "2019-09-21T16:53:28.190Z"
6
  ...
7
}
8
​
Copied!
The other set of data that you need to send along the Order API request is the payment breakdown, to recall the following is sent 

Attribute
Type
Required
Description
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.

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.
1
{ 
2
  ...
3
  "totalPrice": "68.50",
4
  "totalPaid": "68.50",
5
  "totalShipping": "10",
6
  "totalTax": "3"
7
  ...
8
}
9
​
Copied!
Given the above fields, you may notice that the totalPaid amount is 68.50, which is the actual paid amount to your store. This value is the value you need to reward your player with cashback wallet points for (if configured).
In some cases, the total amount of the order may not equal the total paid. For example, this can happen in cases where a discount is applied. Consider the above example where a 10USD discount was applied. The request data will look as following 
1
{ 
2
  ...
3
  "totalPrice": "58.50",
4
  "totalPaid": "48.50",
5
  "totalShipping": "10",
6
  "totalTax": "3",
7
  "totalDiscount":"10"
8
  ...
9
}
Copied!
In addition to order identifier attributes and payment information, you need to send order line items details that include product ID, items categories, vendor, and other important parameters that can be helpful based on your Gameball programs' configurations.
1
{ 
2
  ...
3
   "lineItems":[
4
      {
5
         "productId":"197765",
6
         "category":["accessories"],
7
         "vendor":"Hoxton",
8
         "collection":["4343"],
9
         "title":"The Hoxton"
10
      },
11
     {
12
         "productId":"42366",
13
         "category":["mens"],
14
         "vendor":"Brixton Inc",
15
         "collection":["4343"],
16
         "title":"The Brixton"
17
      }
18
   ]
19
  ...
20
}
Copied!
So the final JSON object will look like this
1
{ 
2
  "playerUniqueId":"player456"
3
  "orderId": "6253e03b",
4
  "orderDate":"2019-09-21T16:53:28.190Z",
5
  "totalPrice": "58.50",
6
  "totalPaid": "58.50",
7
  "totalShipping": "10",
8
  "totalTax": "3"
9
  "totalDiscount":"10" 
10
  "discountCodes": [],
11
  "extra": {},
12
  "redeemedAmount": null,
13
  "holdReference": null,
14
  "lineItems":[
15
      {
16
         "productId":"197765",
17
         "category":["accessories"],
18
         "vendor":"Hoxton",
19
         "collection":["4343"],
20
         "title":"The Hoxton"
21
      },
22
     {
23
         "productId":"42366",
24
         "category":["mens"],
25
         "vendor":"Brixton Inc",
26
         "collection":["4343"],
27
         "title":"The Brixton"
28
      }
29
   ],
30
}
31
​
Copied!
With the event payload sent above, consider that you have the following Gameball Configurations, Cashback enabled with 1 wallet point, the player is rewarded for every 1 USD spent (or as per your configured currency). Additionally, place_order event is created internally as a result of calling Order API.
How the place_order event is created internally 
One of the major advantages of using the Orders API is that you don't have to worry about sending two different requests for the order placement event and cashback reward. In fact, the Order API internally handles sending appropriate data to different modules depending on your Gameball program configurations. 
Here we will explain how the data sent with the Orders API are translated into an event object. Understanding this will help you with linking challenges and messages with placing order events as needed.
Every order sent via Order API is mapped to an place_order event. That’s why the place_order event name is reserved and cannot be created via Gameball’s dashboard. The metadata sent along with the event is composed of the order data sent. This is in addition to key elements that can add value while designing your challenge or message configuration.
Order API attribute 
Mapped to Event Object attribute
totalPaid
total_paid
totalDiscount
total_discount
lineItems[i].weight
weight
lineItems[i].vendor
vendor
lineItems[i].sku
sku
lineItems[i].title
title
lineItems[i].tag
tag
lineItems[i].category
category
lineItems[i].collection
collection
extra.key[0]:value
key[0]:value
The "i" in lineitems[i] denotes any given index in the lineitems array.
Take the below Order API request body 
1
{
2
   "playerUniqueId":"yourPlayerUniqueId",
3
   "orderId":"yourOrderId",
4
   "orderDate":"2021-08-22T22:43:46.314Z",
5
   "totalPaid":95,
6
   "totalPrice":100,
7
   "totalDiscount":5,
8
   "totalShipping":0,
9
   "totalTax":0,
10
   "lineItems":[
11
      {
12
         "productId":"string",
13
         "sku":"sku_value",
14
         "tags":[
15
            "VIP",
16
            "Gold"
17
         ],
18
         "category":[
19
            "electronics",
20
            "cosmetics"
21
         ],
22
         "weight":0,
23
         "vendor":"vendor_value",
24
         "collection":[
25
            "LG",
26
            "Samsung",
27
            "Sony"
28
         ],
29
         "title":"yourTirle"
30
      }
31
   ],
32
   "discountCodes":[
33
      "AU7X-8Q7L",
34
      "BY3V-22GK"
35
   ],
36
   "extra":{
37
      "paymentMethod":"credit card",
38
      "billingAddress":"Alabama"
39
   }
40
​
Copied!
It will be mapped internally to the following event 
1
{
2
   "playerUniqueId":"yourPlayerUniqueId",
3
   "events":{
4
      "place_order":{
5
         "total_paid":95.0,
6
         "total_discount":5.0,
7
         "paymentMethod":"credit card",
8
         "billingAddress":"Alabama",
9
         "weight":0.0,
10
         "vendor":"vendor_value",
11
         "sku":"sku_value",
12
         "title":"yourTirle",
13
         "tag":["VIP","Gold"],
14
         "category":["electronics","cosmetics"],
15
         "collection":["LG","Samsung","Sony"]
16
      }
17
   }
18
}
19
​
Copied!
Accordingly, assume you have the following challenges configured:
First Order challenge to be achieved when a customer places his first order (place_order event is sent)
Trendy look challenge to be achieved when the player purchases two times a product from the accessories category. 
When Orders API is called with the above JSON payload, "player456" status would be as following:
58 wallet points added to his balance 
Challenge First Order is achieved.
Trendy look challenge is in progress with 50% progress.
Tracking Guest Orders
If your store supports guest checkouts, you can also use the Orders API to track guest orders to get ROI analytics through the Gameball dashboard. If the above example order was made by a guest user and not player456 the changes to the request payload would be in two parts 
The first part is the guest flag to be set to true "guest": true
So the complete request will be as following for the case of guest checkout
1
{ 
2
  "playerUniqueId":""
3
  "orderId": "6253e03b",
4
  "orderDate":"2019-09-21T16:53:28.190Z",
5
  "totalPrice": "31.72",
6
  "totalPaid": "21.00",
7
  "totalShipping": "3",
8
  "totalTax": "3",
9
  "totalDiscount":"10.72"  ,
10
  ...
11
  ...
12
  "guest": true
13
}
14
​
Copied!
Points Redemption
Furthermore, Gameball allows the player -with the help of the Order API- to redeem points using either of the two following methods:
​Player redeeming points while placing an order​
​Redeem points using hold​
Player redeeming points while placing an order
Before the player can redeem points from his wallet points balance, you need to show your players their current balance of points and their equivalent monetary value. You can either do this before proceeding to checkout or integrated it inside the checkout process itself. 
To get the player wallet points balance you can use Get Player Balance API. 
cURL
1
curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
2
       -H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d 
3
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/balance'
Copied!
and display it on your UI as needed
If your experience will require the player to redeem before proceeding with the checkout page via a discount coupon or any other form. You can use the Redeem API to redeem points from player's wallet balance and create discount coupons on your system equivilant to the redeemed amount. 

After discount coupons are created, the player can use the created discount coupon normally during your checkout
If redeemtion will be done outside of the checkout page. The order API will not send any redeemption information within its request body
In this use case, we will be discussing redeeming within the checkout using the Order API.

Let’s assume that your customer is visiting your online store. Before proceeding with their order, they would like to redeem 100 points equivalent to 10 USD discount on their placed order.
In this use case, make sure that the redeemed monetary value (10 USD) is passed to the JSON body as follows:
1
{ 
2
  ...
3
  "redeemedAmount": 10,
4
  ...
5
}
6
​
Copied!
In such case, the below fields of the order’s details will differ from the first use case as follows:
1
{ 
2
  ...
3
  "totalPrice": "58.50",
4
  "totalPaid": "58.50",
5
  "totalShipping": "10",
6
  "totalTax": "3"
7
  ...
8
}
9
​
Copied!
And the complete JSON object will look like this:
1
{ 
2
  "playerUniqueId":"player456"
3
  "orderId": "6253e03b",
4
  "orderDate":"2019-09-21T16:53:28.190Z",
5
  "totalPrice": "58.50",
6
  "totalPaid": "58.50",
7
  "totalShipping": "10",
8
  "totalTax": "3",
9
  "lineItems":[
10
      {
11
         "productId":"197765",
12
         "category":["accessories"],
13
         "vendor":"Hoxton",
14
         "collection":["4343"],
15
         "title":"The Hoxton"
16
      },
17
     {
18
         "productId":"42366",
19
         "category":["mens"],
20
         "vendor":"Brixton Inc",
21
         "collection":["4343"],
22
         "title":"The Brixton"
23
      }
24
   ],
25
​
26
  "discountCodes": [],
27
  "extra": {},
28
  "redeemedAmount": 10,
29
  "holdReference": null
30
}
31
​
Copied!
Redeem points using hold
Let’s assume that your system relies on more than one step to process and confirm the placed order. Take for example an Airline booking system where the ticket amount fees are held first, then the seat is confirmed, and finally, the held amount is deducted. Or the order is placed and the player has to pay through external payment gateway. 
For that case and other similar cases, it’s preferable to hold the needed points for redemption before proceeding to place the order. 
Holding points expires after 10 minutes if the checkout process was not completed for any reason.
In this example, you might want to make use of the Hold Points API, then using the returned holdReference in the Orders API payload body as follows:
1
{ 
2
  ...
3
  "redeemedAmount": null,
4
  "holdReference": "1234ref_1009",
5
  ...
6
}
7
​
Copied!