v3.0

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 customers 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 customer's order event and the order details.

  • Redeem points from your customer 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 Customer's Orders

  2. Customer 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 Customer 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 rewards campaigns 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 customer 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

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 customer 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 10 USD discount was applied. The requested data will look as follows: 

{ 
  ...
  "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, and the customer 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 rewards campaigns and messages with placing order events as needed.

Every order sent via Order API is mapped to a 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 rewards campaign 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 rewards campaigns configured:

  • First Order Rewards Campaign to be achieved when a customer places his first order (place_order event is sent)

  • Trendy look Rewards Campaign to be achieved when the customer purchases two times a product from the accessories category.

When Orders API is called with the above JSON payload, "player456" status would be as follows:

  • 58 wallet points added to his balance

  • Rewards Campaign First Order is achieved.

  • Trendy look Rewards Campaign 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 for the guest flag to be set to true "guest": true

So the complete request will be as follows 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
}

Points Redemption

Furthermore, Gameball allows the customer -with the help of the Order API- to redeem points using either of the two following methods:

Customer redeeming points while placing an order

Before the customer can redeem points from his wallet points balance, you need to show your customers their current balance of points and their equivalent monetary value. You can either do this before proceeding to the checkout or integrate it inside the checkout process itself.

To get the customer's wallet points balance you can use Get Customer Balance API. 

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 customer 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 the customer's wallet balance and create discount coupons on your system equivalent to the redeemed amount.

After discount coupons are created, the customer can use the created discount coupon normally during your checkout

If redemption is done outside of the checkout page. The order API should not include any redemption 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, and they would like to redeem 100 points (equivalent to a 10 USD discount) on their placed order before proceeding with their 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
}

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 customer has to pay through an 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 expire 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 use the returned holdReference in the Orders API payload body as follows:

{ 
  ...
  "redeemedAmount": null,
  "holdReference": "1234ref_1009",
  ...
}
PreviousBuild your Own Notification SystemNextRedemption Integration Options

Last updated