Checkout Integration

This guide provides a detailed walkthrough of how to integrate Gameball’s loyalty and rewards features into your checkout process. The integration covers various scenarios to enhance your customers' shopping experience, including loyalty point accumulation, coupon usage, and the ability to preview earned rewards before completing a purchase.

The key scenarios addressed in this guide include:

Earning Loyalty Points: Automatically calculate and assign loyalty points based on a customer's order. Points can be awarded for the total order value, factoring in product prices, discounts, taxes, and shipping fees. This helps customers accumulate points with every purchase, promoting engagement and retention.
Previewing Points Before Completing an Order: Allow customers to view how many points they will earn based on the items in their cart before they proceed with checkout. This feature gives customers visibility into their rewards and can help drive purchases by highlighting loyalty benefits upfront.
Redeeming Loyalty Points During Checkout: Customers can redeem their loyalty points at checkout to reduce the total amount of their order. The system calculates the value of the redeemed points, applies the corresponding discount, and ensures the redemption complies with the configured rules for point usage.
Using Coupons in the Order: Customers can apply coupon codes during checkout to unlock specific discounts or benefits. The system validates the coupon, checks its eligibility criteria, and adjusts the order's total price accordingly.

Each scenario outlines a practical process that focuses on customer interactions, ensuring they can easily navigate loyalty rewards, coupons, and promotions as they make their purchase decisions. This guide will help you integrate these features smoothly into your checkout system, providing customers with a rewarding and seamless experience.

Placing an Order

Start by placing an order. Tracking your customers' completed and paid orders allows you to evaluate key details and gain valuable insights. For example, you may have rewards campaigns configured to be achieved once specific products are purchased.

When the Order API is called, it automatically triggers a place_order event, capturing all the order data as metadata.

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.

The "i" in lineitems[i] denotes any given index in the lineitems array.

Take the example below, where your customer places an order for a "Hoxton Bag". Once the order is successfully placed and paid, the order details will be sent to Gameball via the Order API as follows:

Order Request

customerId string Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer.

orderId string Unique identifier for the order on your system.

orderDate datetime Timestamp of when the order was placed.

totalPaid float The total cost of the order, including all item prices, shipping, taxes, and tips. This value does not account for any discounts or coupons applied and is not used for calculations in Gameball; it is solely saved as historical data linked to the order. Must be a positive value.

totalPrice float The total cost of the order, including all item prices, shipping, taxes, and tips. This value does not account for any discounts or coupons applied and is not used for calculations in Gameball; it is solely saved as historical data linked to the order. Must be a positive value.

totalDiscount float Total discount applied to the order.

totalShipping float Total shipping cost associated with the order.

totalTax float Total tax amount for the order.

lineItems array An array containing details about each product in the order. If not provided, the calculation will only consider the total order values.

lineItems object

productId string Unique identifier for the product or service being purchased.

quantity float Number of units purchased for this product or service.

price float TThe original price of a single product before any tax or discount is applied. This reflects the cost of one unit of the item, not the total for multiple quantities in an order.

Example: If the original price of a product is $50 and a customer buys two units, the price for each item would still be recorded as $50, regardless of quantity.

sku string Stock Keeping Unit (SKU) for the product.

category array Product category, such as fashion or electronics. It can include one or multiple categories. Example: ["natural", "cosmetics"]

collection array Collection ID(s) to which the product belongs. It can include one or multiple collections. Example: ["14313", "4343"]

title string Product title or name.

taxes float The total amount of taxes applied to the line item, expressed in the shop's currency. This amount must be positive and reflects the total taxes based on the quantity of the item.

discount float The total discount applied to this line item, expressed as a positive value. This amount should reflect the total discounts based on the quantity of the item.

{
  "customerId": "15327289462816",
  "orderId": "ORD12345",
  "orderDate": "2024-10-16T08:13:29.290Z",
  "totalPaid": 310,
  "totalPrice": 310,
  "totalShipping": 10,
  "lineItems": [
    {
      "price": 100,
      "quantity": 3,
      "productId": "PROD98765",
      "sku": "SKU98765",
      "title":"Hoxton Bag",
      "category": ["Bags"],
      "collection": ["Summer 2024"],
    }
  ]
}

Order Response

rewardedPoints number The total number of points rewarded to the customer for making this order. These points are typically awarded based on your configured cashback rewards.

lineItems array Details about each product or service in the order, including points rewarded.

lineItems object

productId string Unique identifier for the product or service.

quantity number Number of units purchased for this product or service.

decimalPoints number Fractional points rewarded for this line item.

points number Any points rewarded for this line item.

score number Any score awarded for the line item, if applicable.

{
    "customerId": "15327289462816",
    "redeemedPoints": null,
    "rewardedPoints": 310,
    "lineItems": [
        {
            "productId": "PROD98765",
            "quantity": 3,
            "decimalPoints": 100.0,
            "points": 100
        },
        {
            "productId": "Shipping",
            "quantity": 1,
            "decimalPoints": 10.0,
            "points": 10
        }
    ]
}

Previewing Points Before Placing an Order

Imagine a customer about to make a purchase, and you want to show them the exact points they’ll earn before they complete the order. This is where previewing points comes into play, giving both you and the customer full visibility of the potential rewards before hitting "place order."

Using the Calculate Cashback API , you can display a detailed preview of the points a customer will earn based on the products in their cart. This preview automatically accounts for active transaction campaigns—such as double or triple points—giving customers a clear picture of how their rewards will multiply. By showing the campaign’s start and end dates, you can also create a sense of urgency, encouraging customers to act fast and take advantage of the offer before it expires.

For example, if a customer buys items during a limited-time "triple points" campaign, they can immediately see the added value they’re getting. This not only enhances the customer experience but also motivates them to make the purchase sooner rather than later.

Additionally, this endpoint takes into account any custom cashback rules tied to different customer tiers. This means that customers in higher tiers may receive enhanced rewards, ensuring that each customer’s unique benefits are reflected in the points preview, driving engagement and loyalty.

Calculate Cashback Request

If provided, the cashback calculation will consider the customer's tier. Special tier-based configurations, such as enhanced point accrual rates, may affect the points calculation.

totalPaid float The actual amount paid by the customer for the order, accounting for any discounts or coupons applied. Unlike totalPrice, which reflects the original cost of the order, totalPaid represents the final amount the customer paid at checkout after all adjustments. This value is used for reward calculations in Gameball to determine the points or benefits earned from the order.

Example: A customer purchases items worth $120, including taxes and shipping. If a $20 coupon is applied, the totalPaid becomes $100, reflecting the discounted amount the customer paid. This is the value used to calculate any points or rewards earned from the order.

Example: A customer purchases items worth $120, including taxes and shipping. Even if a $20 coupon is applied, the totalPrice remains $120 as it represents the original cost of the order before any discounts are applied.

totalDiscount float Total discount applied to the order. Must be positive.

totalShipping float Total shipping cost for the order.

lineItems array An array containing details about each product in the order. If not provided, the calculation will only consider the total order values.

lineItems object

productId string Unique identifier for the product or service being purchased.

quantity float Number of units purchased for this product or service.

price float The original price of a single product before any tax or discount is applied. This reflects the cost of one unit of the item, not the total for multiple quantities in an order.

sku string Stock Keeping Unit (SKU) for the product.

collection array Collection ID(s) to which the product belongs. It can include one or multiple collections. Example: ["14313", "4343"]

title string Product title or name.

taxes float The total amount of taxes applied to the line item, expressed in the shop's currency. This amount must be positive and reflects the total taxes based on the quantity of the item.

discount float The total discount applied to this line item, expressed as a positive value. This amount should reflect the total discounts based on the quantity of the item.

{
  "customerId": "cust_12345abc",
  "totalPaid": 350,
  "totalPrice": 350,
  "lineItems": [
    {
      "productId": "875511",
      "price": 150,
      "quantity": 1
    },
    {
      "price": 200,
      "quantity": 1,
      "productSku": "sku123"
    }
  ]
}

Calculate Cashback Response

totalPoints number Total points expected to be earned from the entire order.

totalScore number Total score expected to be earned from the entire order.

lineItems array An array of individual line items and their cashback calculation details.

lineItems object

campaignId number The unique identifier for the active transactional campaign that affects the cashback reward for purchasing this line item. If no campaign is applicable, this field will be null.

campaignName string The name of the active transactional campaign that affects the cashback reward for purchasing this line item. If no campaign is applicable, this field will be null.

campaignEndDate string The end date of the active campaign affecting the line item.This is the date when the campaign will no longer influence points or rewards.

campaignImpactWalletFactor number The multiplier applied by the campaign to the base points calculation. This factor adjusts the final points earned for the line item based on the campaign's impact. Present only if a campaign is applicable.

Example: If the campaign offers 3x points, the campaignImpactWalletFactor would be 3, multiplying the regular points earned by three.

campaignImpactPoints number The total number of points given for this line item due to the campaign's impact. This value reflects the additional points earned from the campaign.

Example: If the base points for an item are 100 and the campaign offers 5x points, the campaignImpactPoints would be 400 (totaling 500 points with the base points included).

productId string Unique identifier for the product.

quantity number The quantity of the product purchased.

totalDecimalPoints number The total decimal points earned for this line item,including any campaign impact.

totalPoints number The total points earned for this line item, including any campaign impact.

Example: If the base points for a product are 50 and a campaign adds 150 points, the totalPoints would be 200.

totalScore number The total score earned for this line item.This value is separate from point and is based on your cashback rewards configuration.

rewardWalletFactor number The multiplier applied to the product price to calculate the base points earned for this line item. This factor represents how many points are earned per unit of currency spent on the product.

Example: If the store rewards 10 points for every $1 spent, the rewardWalletFactor would be 10.

{
  "totalPoints": 19000,
  "lineItems": [
    {
      "productId": "875511",
      "quantity": 1,
      "totalDecimalPoints": 15000.0,
      "totalPoints": 15000,
      "rewardWalletFactor": 20.0
    },
    {
      "quantity": 1,
      "totalDecimalPoints": 4000,
      "totalPoints": 4000
    }
  ]
}

You can use the response to encourage the customer to finalize their purchase faster by showcasing any active campaigns offering extra points compared to the usual rewards. Highlighting these limited-time benefits can create a sense of urgency and motivate the customer to complete their order promptly.

Redeeming Points During an Order

Imagine a customer excited to redeem their hard-earned points while placing an order but still wanting the freedom to browse and add more items to their cart before checking out. With Gameball’s redemption process, you can make this experience smooth and hassle-free by temporarily holding their points.

When the customer opts to redeem points, the Hold Points API allows you to hold those points, generating a unique hold reference ID. This ensures the points are securely reserved for their order, giving the customer peace of mind that their redemption is locked in. They can continue shopping at their own pace, confident that their points are ready to be applied when they're ready to checkout.

Hold Points Request

customerId string

Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.

transactionTime string

The time of the transaction in your system, indicating when the points were held for the customer.

pointsToHold integer

The number of points to be held from the customer’s points balance. This allows you to reserve a certain number of points for later use.

{
  "customerId": "cust_abc12345xyz67890",              
  "transactionTime": "2024-10-11T16:15:15.071Z",                  
  "pointsToHold": 50
}

Hold Points Response

customerId string Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.

holdAmount `number`

The monetary value that has been held from the customer’s points balance. This value represents the amount reserved based on the customer’s available points.

holdEquivalentPoints `number`

The number of points that have been held from the customer’s points balance. These points are reserved for future use or specific transactions.

holdReference `string`

A unique identifier for the hold transaction. This reference is used to track and manage the held points for future actions, such as redeeming the held points or canceling the hold.

{
    "customerId": "cust_abc12345xyz67890",
    "holdAmount": "5",
    "holdEquivalentPoints": 50,
    "holdReference": "a2a199ad-86f3-45c4-8253-7aaee50e4798"
}

Once the customer finalizes their cart, simply use the hold reference "a2a199ad-86f3-45c4-8253-7aaee50e4798"to link the redeemed points to the order API request. This seamless process ensures that their rewards are applied accurately and effortlessly, enhancing their shopping experience.

By providing this flexibility, you not only cater to your customers’ preferences but also build trust and satisfaction, ensuring they enjoy every moment of their loyalty rewards journey with you.

Holding points expire after 10 minutes if the checkout process was not completed for any reason.

Order Request

In addition to the basic attributes outlined in the previous order scenario, such as customerId, orderId, orderDate ,totalPaid , the hold reference will be added within the redemption object to seamlessly link the point redemption to the order the customer placed.

redemption object Redemption details for the order, including points held for redemption.

redemption object

pointsHoldReference string Optional Reference from the Hold Points API for redeeming held points.

{
  ............
  "redemption": {
    "pointsHoldReference": "a2a199ad-86f3-45c4-8253-7aaee50e4798"
  }
}

Order Response

In addition to the response provided in the previous order request, this response includes the redeemed amount, which specifies the exact number of points redeemed during the order.

redeemedPoints number Number of points redeemed by the customer for this order.

{
    ....................
    "redeemedPoints": 50,
    ...................
}

Using Coupon Codes

Using coupon codes during checkout is an effective way to enhance the customer experience and boost sales. By validating and locking a coupon code, businesses can ensure that the discount is reserved exclusively for the customer, eliminating any risk of overuse or misuse. This approach provides a seamless checkout process, where the customer enjoys a personalized discount while the business maintains full control over coupon usage.

This feature is particularly valuable during high-demand campaigns or limited-time promotions, as locking the coupon creates urgency and encourages faster purchasing decisions. By tying the locked coupon to the order, businesses can guarantee accurate tracking of discounts applied and maximize the impact of their promotional efforts. When a customer is shopping and has a coupon code they wish to use, the Validate Coupon API with the lock flag set to true ensures the coupon is securely locked for their exclusive use. This allows the customer to continue shopping confidently, knowing their discount will be applied when they finalize the checkout. This seamless process prevents misuse, streamlines the shopping experience, and encourages quicker purchasing, all while ensuring the discount is properly tracked and applied.

Validate Coupon Request

coupons array A list of coupon codes the customer wants to use that needs to be validated and locked.

lock boolean Indicates whether the request is intended to validate the coupon or to lock it for a future redemption.

You need to set here to True so that the coupon will be locked, meaning that a hold reference will be returned. This hold reference must then be used when placing an order to redeem the coupon. Locking a coupon ensures that the coupon is reserved and cannot be used by others during the lock session.

{
  "customerId": "cust_abc12345xyz67890",
  "coupons": [
    "SUMMER50",
    "FREESHIPPING400"
  ],
  "lock": true
}

Validate Coupon Response

The response indicates whether the provided coupon code is valid and if it can be used by the customer when completing their order. If the coupon is valid, it will be marked as eligible for use, allowing the customer to apply the discount during checkout. If invalid, the response will indicate the reason the coupon cannot be used.

valid boolean Indicates whether the coupons are valid.

Example: true if the coupon is eligible for use by the customer, and false if the coupon cannot be applied to the customer's order.

coupons arrayAn array containing the details of the coupons that need to be locked or validated in the request.

Coupon Object

code string The generated coupon code that the customer will use.

type string Type of the coupon, such as fixed amount, percentage discount, free shipping, or product-specific coupon.Possible Values :

shipping
fixed
percentage
product

value number The monetary value or percentage value of the coupon, depending on its type. Example: If a coupon provides a $100 discount, the value will be 100.

usageLimit number The total number of times the coupon can be used across all customers. Example: If a coupon can only be used once, the usageLimit will be set to 1, indicating that it cannot be reused after the first use.

limitPerCustomer number The number of times a single customer can use the coupon. Example: If each customer can only use the coupon one time, the limitPerCustomer will be set to 1, ensuring the coupon can only be redeemed once per customer.

startDate string The date and time when the coupon becomes valid and can be used. Example: If the coupon becomes valid on October 17, 2024, the startDate will be "2024-10-17T08:22:00.0000Z".

expiryDate string The date and time when the coupon will expire and no longer be valid. Example: If the coupon expires on October 17, 2027, the expiryDate will be "2027-10-17T08:22:00.0000Z".

capping number The maximum discount or value cap that the coupon can offer, even if the discount calculation exceeds this value. Example: If the maximum discount for the coupon is capped at $400, the capping will be set to 400, meaning the discount will not exceed that amount.

minReward number Specifies the minimum discount value a customer is guaranteed to receive when using a percentage-based discount coupon. If the calculated discount from the percentage is less than this value, the customer will still receive the minReward amount as a discount.

Example: Suppose a customer has a 10% discount coupon with a minReward of $5. If they make a purchase of $30, the 10% discount would ordinarily give them $3 off. However, since minReward is set to $5, the customer will receive the higher $5 discount instead. If they make a purchase of $60, the 10% discount would yield $6, which is above the minReward value, so they receive the full $6 discount.

minOrderValue number The minimum order value required for the coupon to be applied. Example: If the coupon requires a minimum purchase of $1,000 to apply, the minOrderValue will be 1000.

entitledProductIds array A list of product IDs that are eligible for the coupon. If provided, only these products can benefit from the coupon. Example: If the coupon is only valid for a specific product, the entitledProductIds array may contain IDs like ["productId123"] to indicate that only this product is eligible for the discount.

entitledVariantIds array A list of product variant IDs that are eligible for the coupon. If provided, only these product variants can benefit from the coupon. Example: If the coupon is valid for specific product variants, the entitledVariantIds array might include IDs like ["variantId456"], limiting the coupon to these variants.

entitledCollectionIds array A list of collection IDs that are eligible for the coupon. If provided, only these collections can benefit from the coupon. Example: If the coupon applies to an entire collection of products, the entitledCollectionIds array could include ["collectionId789"], indicating which collections the coupon can be used on.

combinesWith.orderDiscounts boolean Indicates if the coupon can be combined with order-level discounts. Example: If the coupon cannot be combined with order discounts, this field will be set to false, ensuring that the coupon and other discounts will not apply together.

combinesWith.productDiscounts boolean Indicates if the coupon can be combined with product-specific discounts. Example: If the coupon cannot be used with existing product discounts, combinesWith.productDiscounts will be false, preventing customers from stacking discounts.

combinesWith.shippingDiscounts boolean Indicates if the coupon can be combined with shipping discounts. Example: If the coupon cannot be combined with free shipping offers, combinesWith.shippingDiscounts will be false.

lockReference string The unique reference code associated with the coupon lock session. This reference ensures that the coupon is reserved exclusively for the current session and cannot be used elsewhere until the lock expires or is released. This lock reference is essential for linking the coupon to the order, and it must be included in the Order API request to apply the coupon to the customer's final order.

dateToExpire string The exact date and time when the coupon lock will expire, after which the coupon will be available for others to use again or for another session. Example: If the lock is set to expire on October 20, 2024, the dateToExpire might be "2024-10-20T16:22:00.8249283Z", indicating the precise moment the lock is lifted.

Sample Response

{
  "valid": true,
  "coupons": [
    {
      "code": "SUMMER50",
      "type": "percentage",
      "value": 50,
      "usageLimit": 100,
      "limitPerCustomer": 1,
      "startDate": "2024-10-20T14:16:00Z",
      "expiryDate": "2025-01-20T15:14:00Z",
      "capping": 400,
      "minOrderValue": 1000,
      "entitledProductIds": ["prod_abc123", "prod_xyz456"],
      "entitledVariantIds": ["variant_red_large", "variant_blue_small"],
      "entitledCollectionIds": ["summer_sale", "winter_wear"],
      "combinesWith": {
        "orderDiscounts": true,
        "productDiscounts": true,
        "shippingDiscounts": true
      }
    },
    {
      "code": "FREESHIPPING400",
      "type": "shipping",
      "value": 0,
      "usageLimit": 200,
      "limitPerCustomer": 5,
      "startDate": "2024-10-20T14:22:00Z",
      "expiryDate": "2025-06-29T14:16:00Z",
      "capping": 250,
      "minOrderValue": 400,
      "entitledProductIds": null,
      "entitledVariantIds": null,
      "entitledCollectionIds": null,
      "combinesWith": {
        "orderDiscounts": true,
        "productDiscounts": false,
        "shippingDiscounts": true
      }
    }
  ],
  "lockReference": "74e20fc6bf7a4970ad3c125b1713194f",
  "dateToExpire": "2024-10-20T16:22:00.8249283Z"
}

To apply the coupon codes for the customer when completing the order, you will use the lockReference returned in the coupon validation response. This ensures that the coupon is reserved for the customer during the checkout process.

Order Request

In addition to the basic attributes outlined in the previous order scenario, such as customerId, orderId, orderDate ,totalPaid ,you will also include the couponsLockReference within the redemption object. This new attribute will link the locked coupon to the order, ensuring that the coupon is applied when the customer completes the checkout process.

redemption object Redemption details for the order, including coupons that will be used in this order.

redemption object

couponsLockReference string The lock reference for the coupon is a unique identifier used to "lock" a coupon for a specific customer or order. This prevents the coupon from being used by others or on multiple transactions.

{
  ............
  "redemption": {
    "couponsLockReference": "a2a199ad-86f3-45c4-8253-7aaee50e4798"
  }
}

PreviousCustomer experience for coupon conversion

Last updated 4 days ago

Placing an Order

Order Request

Order Response

Previewing Points Before Placing an Order

Calculate Cashback Request

Calculate Cashback Response

Redeeming Points During an Order

Hold Points Request

Hold Points Response

holdAmount number

holdEquivalentPoints number

holdReference string

Order Request

Order Response

Using Coupon Codes

Validate Coupon Request

Validate Coupon Response

Sample Response

Order Request

Placing an Order

Order Request

Order Response

Previewing Points Before Placing an Order

Calculate Cashback Request

Calculate Cashback Response

Redeeming Points During an Order

Hold Points Request

Hold Points Response

holdAmount number

holdEquivalentPoints number

holdReference string

Order Request

Order Response

Using Coupon Codes

Validate Coupon Request

Validate Coupon Response

Sample Response

Order Request

holdAmount `number`

holdEquivalentPoints `number`

holdReference `string`

holdAmount `number`

holdEquivalentPoints `number`

holdReference `string`