Skip to main content

​
Overview

Validating coupons is a critical step in the checkout process to ensure fairness, prevent misuse, and provide a smooth customer experience. This tutorial walks you through how to use Gameball’s coupon validation APIs to: Whether you’re building a custom UI or handling redemptions manually outside the Gameball widget, this process is essential for protecting campaign integrity and ensuring real-time accuracy.

​
When to Use This

Use this API before applying any coupon at checkout to:

​
Widget vs. Custom UI

Gameball Widget

Automatically validates and locks coupons for you.

Custom UI

You must call the validation API and store lock references yourself.

​
Key Concepts

​
1. Validation and Locking Process

The full flow includes:
  • Step 1: Check coupon validity
  • Step 2: Verify if the order meets eligibility rules (e.g., minimum spend, active status)
  • Step 3: Lock the coupon temporarily to avoid conflicts
  • Step 4: Return discount details for customer preview

​
2. Locking Coupons

Setting "lock": true in your validation request reserves the coupon for that customer/session, returns a lockReference token, and prevents others from using the same coupon in parallel until the session completes or times out. This is essential in high-traffic environments.

​
Use Case 1: Validate a Single Coupon

Scenario: A customer enters the code SAVE10 at checkout. You want to verify it’s active, applicable to their order, and lock it for usage.

​
API: POST /validate-coupons

​
Request:

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

​
Response:

{
  "lockReference": "5e21ff4baf5d4760a8a43c7b2513298e",
  "valid": true,
  "coupons": [
    {
      "code": "SAVE10",
      "type": "fixed_discount",
      "value": 10
    }
  ]
}

​
What Gameball Does:

  • Validates if the coupon SAVE10 is active and applicable to this customer
  • Locks the coupon temporarily
  • Returns the type of coupon (e.g., fixed discount, free shipping)
  • Returns the value of the discount

​
Developer Notes:

  • Save the lockReference. You’ll need it when submitting the order or triggering redemption.
  • Do not skip validation. Redeeming without prior validation may result in failure or incorrect discounts.

​
Use Case 2: Validate and Lock Multiple Coupons

Scenario: Your checkout allows stacking coupons, for example, applying both a fixed discount (SAVE10) and free shipping (FREESHIP) together. You need to:
  • Validate both coupons
  • Lock them simultaneously to avoid race conditions
  • Display the combined discount to the customer

​
API: POST /validate-coupons

​
Request:

{
  "customerId": "cust_12345",
  "coupons": ["SAVE10", "FREESHIP"],
  "lock": true
}

​
Response:

{
  "lockReference": "abc123lock",
  "valid": true,
  "coupons": [
    {
      "code": "SAVE10",
      "type": "fixed_discount",
      "value": 10
    },
    {
      "code": "FREESHIP",
        "type": "free_shipping",
      "value": 0
    }
  ]
}

​
What Gameball Does:

  • Validates all coupons atomically
  • Locks both coupons under a single lockReference
  • Returns metadata about each coupon

​
When This is Helpful:

  • Your platform supports stacking multiple coupons on a single order
  • You want to validate and lock them in a single request for performance
  • You need a shared lock token to pass during final redemption

​
What Happens if a Coupon is Invalid?

If any coupon is:
  • Expired
  • Not applicable to this customer
  • Outside the campaign window
  • Already locked by another session
Then the valid field will return false, and the failed coupon will be listed with error metadata. Example: 
{
  "valid": false,
  "coupons": [
    {
      "code": "SAVE10",
      "valid": false,
      "reason": "expired"
    }
  ]
}

Validate Coupon API

Eligibility and lock flow for a single coupon

Validate Multiple Coupons API

Validate stacked coupons in one atomic request

Burn Coupon API

Finalize coupon usage after payment success

Release Coupon API

Unlock coupons if checkout fails or is canceled

​
Key Takeaways