Gameball Couponing Engine

Gameball’s couponing engine provides a streamlined way to handle coupon validation, locking, redemption (burning), and releasing. This guide walks you through the steps to integrate couponing into your system, allowing customers to seamlessly use coupons at checkout.

Before using the couponing engine, make sure it’s set up in the Gameball dashboard. Configuration includes setting redemption rules, usage limits, discount types, and other eligibility criteria. Once configured, you can integrate Gameball’s coupon API for automated coupon management and redemption flows.

To enable this feature, please contact our support team. Once requested, our team will assist in activating the feature for your account.

---

Integration Walkthrough

1. Generating a Coupon

To generate a coupon, use the Generate Coupon API. This API call creates a coupon for the customer based on the redemption rule configured in Gameball. The redemption rule determines the number of points required to redeem the coupon, the discount type, and any minimum order requirements.

Example Use Case

Generate a $10 Discount Coupon for a Loyal Customer: You want to provide a $10 discount to a loyal customer. Use the Generate Coupon API with the customer’s ID and the applicable rule ID for the reward.

{
  "ruleId": "12345",
  "customerId": "customer123",
  "email": "[e-mail]",
  "mobile": "[phone]"
}

The response provides details about the generated coupon, including the coupon code, validity period, usage limit, discount value, and any minimum order requirements.

{
  "code": "SAVE10",
  "startDate": "2024-11-01T00:00:00Z",
  "expiryDate": "2024-12-01T23:59:59Z",
  "usageLimit": 1,
  "discountValue": 10,
  "minOrderValue": 50,
  "type": "fixed"
}

---

2. Validating and Locking Coupons

To validate and optionally lock a coupon, use the Validate Single Coupon API for a single coupon or the Validate Multiple Coupons API for multiple coupons. Setting the lock flag to true locks the coupon, reserving it for the customer until checkout. The system will return a lockReference, which will be needed in the next steps.

Example Use Cases

Single Coupon Validation and Locking: A customer applies the SAVE10 coupon at checkout. Use the Validate Single Coupon API to validate and lock the coupon exclusively for this customer.

{
  "customerId": "customer123",
  "mobile": "010XXXXXXXX",
  "email": "[e-mail]",
  "lock": true,
  "lockReference": null
}

The system will return a lockReference along with coupon details, which can be used in the next step.

{
  "lockReference": "74e20fc6bf7a4970ad3c125b1713194f",
  "valid": true,
  "coupon": {
    "code": "SAVE10",
    "type": "fixed",
    "value": 10,
    "usageLimit": 1,
    "limitPerCustomer": 1,
    "startDate": "2024-11-01T00:00:00Z",
    "expiryDate": "2024-12-01T23:59:59Z"
  }
}

Multiple Coupons Validation and Locking: A customer uses two coupons, SAVE10 and FREESHIP, for their order. Use the Validate Multiple Coupons API to validate and lock both coupons for this transaction.

{
  "customerId": "customer123",
  "coupons": ["SAVE10", "FREESHIP"],
  "lock": true,
  "lockReference": null
}

The system returns a lockReference and details for each validated coupon.

{
  "lockReference": "5e21ff4baf5d4760a8a43c7b2513298e",
  "valid": true,
  "coupons": [
    {
      "code": "SAVE10",
      "type": "fixed",
      "value": 10
    },
    {
      "code": "FREESHIP",
      "type": "shipping",
      "value": 0
    }
  ]
}

---

3. Burning or Releasing Locked Coupons

Once the coupon is validated and locked, you have two options based on the customer’s transaction:

• Burn the Coupon: If the customer completes the purchase, use the Burn Coupons API with the lockReference to finalize redemption, applying the discount.

{
  "lockReference": "5e21ff4baf5d4760a8a43c7b2513298e"
}

A successful coupon burn request will return a 204 No Content status code, confirming that the coupons have been burned successfully.

• Release the Coupon: If the transaction does not proceed, release the coupon(s) to make them available for future use. Use the Release Coupons API with the same lockReference.

{
  "lockReference": "5e21ff4baf5d4760a8a43c7b2513298e"
}

A successful coupon burn request will return a 204 No Content status code, confirming that the coupons have been released successfully.

---

Additional Operations to Consider

• Reverse Coupon Burn: If a redeemed coupon needs to be reversed (for instance, if the customer cancels the order), use the Reverse Coupon Burn API with the original lockReference to make the coupon valid again.

• Reverse Lock: If you need to release a locked coupon within the 10-minute window without redeeming it, use the Reverse Lock API to unlock the coupon.

Gameball’s couponing engine ensures a smooth experience for managing and redeeming coupons. For additional details, refer to the Coupon API documentation. For a simpler and more secure approach, we recommend using the coupon system over direct redemption.