Gameball Couponing Engine Integration

Enable your customers to convert loyalty points into discount coupons and apply them at checkout with secure, API-driven flows. Gameball’s built-in coupon engine makes issuing, validating, and redeeming coupons easy, across both web and mobile.

Why Use Gameball’s Couponing Engine?

Gameball’s native engine provides:

Unique coupon code generation (SAVE10, FREESHIP, etc.)
Real-time coupon validation and locking to prevent misuse
Direct coupon application at checkout via API
Refund-safe logic (burn or release on success/failure)
Omnichannel support, coupons work online and in-store

Implementation Overview

Gameball supports two implementation paths:

Implementation	Description
Gameball Widget	Coupon creation, visibility, and redemption are handled automatically via the widget. You only need to validate and apply coupons at checkout.
Custom UI	You are responsible for displaying reward options, generating coupons, and surfacing them at checkout using Gameball’s APIs.

Step-by-Step Integration (with Both Flows)

Step 1: Show Available Redemption Options

Gameball Widget
Custom UI

You must fetch and display all eligible redemption options.

API:GET /customers//redemption-configurations

{
  "redemptionConfigurations": [
    {
      "id": 2138,
      "title": "Redeem 100 Points for $10 OFF",
      "pointsRequired": 100,
      "coupon": {
        "couponType": "fixed",
        "discountValue": 10.0,
        "currency": "USD",
        "validityDays": 30
      }
    },
    {
      "id": 2139,
      "title": "Redeem 200 Points for Free Shipping",
      "pointsRequired": 200,
      "coupon": {
        "couponType": "free_shipping",
        "validityDays": 15
      }
    }
  ]
}

Step 2: Generate Coupon

Gamball Widget
Custom UI

You must call the Generate Coupon API when a customer chooses a reward. By pressing the redeem button, the Generate Coupon API should be triggered, where the output is another UI representing the coupon generated with the coupon code from the API’s response for the customer to use

{
  "ruleId": "12345",
  "customerId": "customer123",
  "email": "customer@example.com",
  "mobile": "+1234567890"
}

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

Step 3: Display Coupons at Checkout

Gameball Widget
Custom UI

You must fetch and show all active customer coupons on your checkout page.

Couponredemption Ezgif Com Video To Gif Converter Gi

API:GET /customers//coupons

{
  "coupons": [
    {
      "code": "GB2024",
      "type": "percentage_discount",
      "value": 15,
      "expiryDate": "2024-12-31T23:59:59Z",
      "isUsed": false
    },
    {
      "code": "GBFREESHIP",
      "type": "free_shipping",
      "value": 0,
      "expiryDate": "2024-11-30T23:59:59Z",
      "isUsed": false
    }
  ]
}

Suggested UI Behavior:

Show coupon name, value, and expiry
Allow the customer to select one, which fills the input field automatically

Step 4: Validate & Lock the Coupon

API Options:

Use Case: Mixed Coupons Applied in a Single Order Imagine your checkout allows customers to stack or combine different coupon types on the same order. For example:

One discount coupon: SAVE10 ($10 off)
One free shipping coupon: FREESHIP (waives shipping fees)

At checkout, the customer selects both coupons to maximize savings. You must:

Verify that each coupon is still valid and not expired.
Lock both coupons together so no other session can reuse them while the customer completes payment.

In this case, POST /validate-coupons lets you validate and lock both in one atomic call.

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

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

Save the lockReference. It is required in the next step.

When This is Helpful:

You allow multiple coupon stacking in one order
You need to lock them together to avoid conflicts
You want to handle validation in one API call for efficiency

Step 5: Burn (Apply) the Coupon

Option A: Burn Manually POST /burn-coupon

{
  "lockReference": "5e21ff4baf5d4760a8a43c7b2513298e"
}

Option B: Use Order API (Recommended) POST /order

{
  "customerId": "customer123",
  "orderId": "ORD123",
  "totalPaid": 90,
  "orderDate": "2024-10-16T12:00:00Z",
  "redemption": {
    "lockReference": "5e21ff4baf5d4760a8a43c7b2513298e"
  }
}

The Order API burns the coupon and logs the order in one step.

Step 6: Release Coupon (If Checkout Fails or Is Abandoned)

Couponrelease Ezgif Com Video To Gif Converter Gi

Manual Release API: POST /release-coupon

{
  "lockReference": "5e21ff4baf5d4760a8a43c7b2513298e"
}

Automatic Release:Configure the timeout duration in your Gameball dashboard under Coupon Settings.

Summary Table

Step	API	Widget	Custom UI
1. Show Redemption Options	GET /redemption-configurations	(Auto)	(Manual)
2. Generate Coupon	POST /generate-coupon	Auto	(Manual)
3. Display Coupons	GET /customers/id/coupons	Auto	(Manual)
4. Validate & Lock	POST /validate-coupon(s)	Auto	Required
5. Burn/Apply	POST /burn-coupon or POST /order	Manual	✅
6. Release	POST /release-coupon	❌	✅

Generate Coupon API

Issue coupons from Gameball’s built-in engine

Get Customer Coupons API

Display coupons generated for a customer

Validate Coupon API

Confirm coupon eligibility before checkout

Burn Coupon API

Finalize coupon usage after successful payment

Getting Started

General

Experiences

More

Redeem Through Gameball Discount Engine

Gameball Couponing Engine Integration

Why Use Gameball’s Couponing Engine?

Implementation Overview

Step-by-Step Integration (with Both Flows)

Step 1: Show Available Redemption Options

Step 2: Generate Coupon

Step 3: Display Coupons at Checkout

Step 4: Validate & Lock the Coupon

Step 5: Burn (Apply) the Coupon

Step 6: Release Coupon (If Checkout Fails or Is Abandoned)

Summary Table

Generate Coupon API

Get Customer Coupons API

Validate Coupon API

Burn Coupon API

Getting Started

General

Experiences

More

Documentation Index

​Gameball Couponing Engine Integration

​Why Use Gameball’s Couponing Engine?

​Implementation Overview

​Step-by-Step Integration (with Both Flows)

​Step 1: Show Available Redemption Options

​Step 2: Generate Coupon

​Step 3: Display Coupons at Checkout

​Step 4: Validate & Lock the Coupon

​Step 5: Burn (Apply) the Coupon

​Step 6: Release Coupon (If Checkout Fails or Is Abandoned)

​Summary Table

​Related Resources

Generate Coupon API

Get Customer Coupons API

Validate Coupon API

Burn Coupon API

Gameball Couponing Engine Integration

Why Use Gameball’s Couponing Engine?

Implementation Overview

Step-by-Step Integration (with Both Flows)

Step 1: Show Available Redemption Options

Step 2: Generate Coupon

Step 3: Display Coupons at Checkout

Step 4: Validate & Lock the Coupon

Step 5: Burn (Apply) the Coupon

Step 6: Release Coupon (If Checkout Fails or Is Abandoned)

Summary Table

Related Resources