Skip to main content

​
What Does This Integration Do?

Instead of using Gameball’s native coupon engine, Gameball can send a real-time HTTP request to your system when:
  • A customer redeems points for a coupon reward
  • A customer completes a campaign and earns a coupon
Your system then returns a valid coupon code, which Gameball shows to the customer.

​
Supported Use Cases

ScenarioExample
Redeem PointsAdam redeems 500 points and receives a 10% OFF code
Campaign RewardSarah completes a mission and earns a $20 coupon

​
Flow: How Gameball Communicates With Your System

1

Customer initiates a redemption (or completes a campaign)

2

Gameball sends a POST request to your specified endpoint

3

Your system generates the coupon and returns the code

4

Gameball shows the code to the user in their profile or reward message

5

Customer copies/pastes the code at checkout on your store

​
Implementation Guide

​
Step-by-Step Integration Flow

​
Step 1: Configure Gameball to Call Your Endpoint

Gameball WidgetCustom UI
Configuration required only once — the rest is handled internally.Same configuration required — you control how the coupon is generated/displayed.
Gameball needs to know how to reach your couponing engine:
FieldDescription
urlYour coupon generation endpoint, e.g., https://api.yourapp.com/create-coupon
methodUsually POST
contentTypeTypically application/json
headersAuth or token headers, if needed
payloadThe request body Gameball will send
couponMappingMap Gameball coupon types to your supported types
platformsPlatforms where the coupon applies (e.g., web, mobile, POS)

​
Step 2: Configure via API (Optional)

You can configure this directly via API: API: POST /api/v1/coupons/configure Authorization: Bearer YOUR_API_TOKEN Content-Type: application/json 
{
  "url": "https://yourdomain.com/api/coupons",
  "method": "POST",
  "contentType": "application/json",
  "headers": [
    { "key": "Authorization", "value": "Bearer 123456" }
  ],
  "payload": {
    "code": "{{code}}",
    "value": "{{amount}}",
    "couponType": "{{discount_type}}"
  },
  "couponMapping": {
    "percentage": true,
    "fixed": true,
    "freeShipping": true
  },
  "platforms": ["web", "mobile"]
}

​
Step 3: Build Your Coupon Creation Endpoint

This is your own API that Gameball will call. Example (Node.js): 
app.post('/api/coupons', (req, res) => {
  const { code, value, customerId } = req.body;
  // Create and store the coupon
  res.status(200).send({ couponCode: code });
});
You must return HTTP 200 and include the coupon code in the response.

​
Step 4: Test the Connection

Gameball WidgetCustom UI
Use “Test Connection” from Gameball dashboard to simulate coupon creation.Same. Useful for debugging or dry-run integration.
API (to retrieve config): GET /api/v1/coupons/configuration Authorization: Bearer YOUR_API_TOKEN

​
Coupon Redemption Flows

Gameball supports two primary coupon generation flows, both of which work with either the Gameball widget or your custom UI.

​
1. Manual Coupon Redemption

​
Overview

Gameball WidgetCustom UI
Redemption flow is fully handled: point display, coupon generation, and coupon listing.You handle reward options, redemption calls, and coupon display manually.

​
Step-by-Step: Widget-Based Manual Redemption

Step 1: Customer opens the widget → Gameball displays points balance and redemption options. image (121).png Step 2: Customer selects a reward → Gameball sends a webhook to your backend and shows the returned coupon in My Coupons. Redemptionthroughwidget Ezgif Com Video To Gif Converter Gi Step 3: At checkout, the customer applies the coupon. You use: Couponredemption Ezgif Com Video To Gif Converter Gi 
POST /order

{
  "customerId": "cust_12345",
  "orderId": "ORD123",
  "totalPaid": 135,
  "coupons": {
    "couponCodes": ["GB1023"]
  }
}

​
Step-by-Step: Custom UI Manual Redemption

Step 1: Fetch Redemption Options GET /redemption-configs 
{
  "redemptionRules": [
    {
      "id": 2138,
      "pointsToRedeem": 100,
      "coupon": {
        "couponType": "fixed_rate_discount",
        "discountValue": 10
      }
    }
  ]
}
Step 2: Redeem Points POST /redeem 
{
  "playerUniqueId": "cust_12345",
  "ruleId": 2138,
  "transactionId": "txn_001",
  "transactionTime": "2024-11-01T12:00:00Z"
}

{
  "couponCode": "GB1023",
  "redeemEquivalentPoints": 100
}
Step 3: Display Earned Coupons GET /customers//coupons Step 4: Apply at Checkout Same as widget, use the POST /order API. Couponredemption Ezgif Com Video To Gif Converter Gi

​
2. Campaign-Based Coupon Rewards

Widget automatically shows campaign-earned coupons in “My Coupons”.image (122).png

​
Step-by-Step: Widget Campaign Flow

  • Gameball displays the coupon in real-time once earned from a campaign.
  • No API integration needed to show it.
  • At checkout, use POST /order as shown earlier.

Redeem Points API

Convert loyalty points into coupon rewards

Generate Coupon API

Use Gameball’s engine when you don’t need custom issuance

Get Customer Coupons API

Display coupons created by your backend

Gameball Coupon Engine Tutorial

Learn the built-in alternative to custom coupon generation