Skip to main content

​
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:
ImplementationDescription
Gameball WidgetCoupon creation, visibility, and redemption are handled automatically via the widget. You only need to validate and apply coupons at checkout.
Custom UIYou 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

Handled by the widget, the customer sees eligible redemption options inside the widget.Image(124) Pn

​
Step 2: Generate Coupon

Automatically triggered inside the widget when a redemption is made. No API call is needed.Redemptionthroughwidget Ezgif Com Video To Gif Converter Gi

​
Step 3: Display Coupons at Checkout

Customers can open “My Coupons” inside the widget to copy and apply a coupon.Viewmycouponsonwidget Ezgif Com Video To Gif Converter Gi

​
Step 4: Validate & Lock the Coupon

Not handled by widget. You must validate and lock the coupon before applying it at checkout.
Couponredemption Ezgif Com Video To Gif Converter Gi 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:
  1. Verify that each coupon is still valid and not expired.
  2. 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

Not handled by the widget. You must finalize the coupon usage.
Couponredemption Ezgif Com Video To Gif Converter Gi 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)

Not handled by widget. You must manually release or rely on timeout.
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

StepAPIWidgetCustom UI
1. Show Redemption OptionsGET /redemption-configurations(Auto)(Manual)
2. Generate CouponPOST /generate-couponAuto(Manual)
3. Display CouponsGET /customers/id/couponsAuto(Manual)
4. Validate & LockPOST /validate-coupon(s)AutoRequired
5. Burn/ApplyPOST /burn-coupon or POST /orderManual✅
6. ReleasePOST /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