Checkout Integration Example
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:
So let’s dive into each use case.
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
{
...
"playerUniqueId": "player456",
"orderId": "6253e03b",
"orderDate": "2019-09-21T16:53:28.190Z"
...
}
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. |
{
...
"totalPrice": "68.50",
"totalPaid": "68.50",
"totalShipping": "10",
"totalTax": "3"
...
}
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
{
...
"totalPrice": "58.50",
"totalPaid": "48.50",
"totalShipping": "10",
"totalTax": "3",
"totalDiscount":"10"
...
}
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.
{
...
"lineItems":[
{
"productId":"197765",
"category":["accessories"],
"vendor":"Hoxton",
"collection":["4343"],
"title":"The Hoxton"
},
{
"productId":"42366",
"category":["mens"],
"vendor":"Brixton Inc",
"collection":["4343"],
"title":"The Brixton"
}
]
...
}
So the final JSON object will look like this
{
"playerUniqueId":"player456"
"orderId": "6253e03b",
"orderDate":"2019-09-21T16:53:28.190Z",
"totalPrice": "58.50",
"totalPaid": "58.50",
"totalShipping": "10",
"totalTax": "3"
"totalDiscount":"10"
"discountCodes": [],
"extra": {},
"redeemedAmount": null,
"holdReference": null,
"lineItems":[
{
"productId":"197765",
"category":["accessories"],
"vendor":"Hoxton",
"collection":["4343"],
"title":"The Hoxton"
},
{
"productId":"42366",
"category":["mens"],
"vendor":"Brixton Inc",
"collection":["4343"],
"title":"The Brixton"
}
],
}
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.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
{
"playerUniqueId":"yourPlayerUniqueId",
"orderId":"yourOrderId",
"orderDate":"2021-08-22T22:43:46.314Z",
"totalPaid":95,
"totalPrice":100,
"totalDiscount":5,
"totalShipping":0,
"totalTax":0,
"lineItems":[
{
"productId":"string",
"sku":"sku_value",
"tags":[
"VIP",
"Gold"
],
"category":[
"electronics",
"cosmetics"
],
"weight":0,
"vendor":"vendor_value",
"collection":[
"LG",
"Samsung",
"Sony"
],
"title":"yourTirle"
}
],
"discountCodes":[
"AU7X-8Q7L",
"BY3V-22GK"
],
"extra":{
"paymentMethod":"credit card",
"billingAddress":"Alabama"
}
It will be mapped internally to the following event
{
"playerUniqueId":"yourPlayerUniqueId",
"events":{
"place_order":{
"total_paid":95.0,
"total_discount":5.0,
"paymentMethod":"credit card",
"billingAddress":"Alabama",
"weight":0.0,
"vendor":"vendor_value",
"sku":"sku_value",
"title":"yourTirle",
"tag":["VIP","Gold"],
"category":["electronics","cosmetics"],
"collection":["LG","Samsung","Sony"]
}
}
}
Accordingly, assume you have the following challenges configured:
- First Order challenge to be achieved when a customer places his first order (
place_orderevent 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.
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": trueSo the complete request will be as following for the case of guest checkout
{
"playerUniqueId":""
"orderId": "6253e03b",
"orderDate":"2019-09-21T16:53:28.190Z",
"totalPrice": "31.72",
"totalPaid": "21.00",
"totalShipping": "3",
"totalTax": "3",
"totalDiscount":"10.72" ,
...
...
"guest": true
}
Furthermore, Gameball allows the player -with the help of the Order API- to redeem points using either of the two following methods:
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.
cURL
curl -X GET -H 'apiKey: 807b041b7d35425988e354e1f6bce186' \
-H 'secretKey: klmb041b7d354259l3u4ft35e1q2r3703' -d
-v -i 'https://api.gameball.co/api/v3.0/integrations/player/player456/balance'
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:
{
...
"redeemedAmount": 10,
...
}
In such case, the below fields of the order’s details will differ from the first use case as follows:
{
...
"totalPrice": "58.50",
"totalPaid": "58.50",
"totalShipping": "10",
"totalTax": "3"
...
}
And the complete JSON object will look like this:
{
"playerUniqueId":"player456"
"orderId": "6253e03b",
"orderDate":"2019-09-21T16:53:28.190Z",
"totalPrice": "58.50",
"totalPaid": "58.50",
"totalShipping": "10",
"totalTax": "3",
"lineItems":[
{
"productId":"197765",
"category":["accessories"],
"vendor":"Hoxton",
"collection":["4343"],
"title":"The Hoxton"
},
{
"productId":"42366",
"category":["mens"],
"vendor":"Brixton Inc",
"collection":["4343"],
"title":"The Brixton"
}
],
"discountCodes": [],
"extra": {},
"redeemedAmount": 10,
"holdReference": null
}
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:
{
...
"redeemedAmount": null,
"holdReference": "1234ref_1009",
...
}