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
| Scenario | Example |
|---|
| Redeem Points | Adam redeems 500 points and receives a 10% OFF code |
| Campaign Reward | Sarah completes a mission and earns a $20 coupon |
Flow: How Gameball Communicates With Your System
Customer initiates a redemption (or completes a campaign)
Gameball sends a POST request to your specified endpoint
Your system generates the coupon and returns the code
Gameball shows the code to the user in their profile or reward message
Customer copies/pastes the code at checkout on your store
Implementation Guide
Step-by-Step Integration Flow
| Gameball Widget | Custom UI |
|---|
| Configuration required only once — the rest is handled internally. | Same configuration required — you control how the coupon is generated/displayed. |
| Field | Description |
|---|
| url | Your coupon generation endpoint, e.g., https://api.yourapp.com/create-coupon |
| method | Usually POST |
| contentType | Typically application/json |
| headers | Auth or token headers, if needed |
| payload | The request body Gameball will send |
| couponMapping | Map Gameball coupon types to your supported types |
| platforms | Platforms where the coupon applies (e.g., web, mobile, POS) |
{
"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 Widget | Custom UI |
|---|
| Use “Test Connection” from Gameball dashboard to simulate coupon creation. | Same. Useful for debugging or dry-run integration. |
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 Widget | Custom UI |
|---|
| Redemption flow is fully handled: point display, coupon generation, and coupon listing. | You handle reward options, redemption calls, and coupon display manually. |
Step 2:
Customer selects a reward → Gameball sends a webhook to your backend and shows the returned coupon in My Coupons.
Step 3:
At checkout, the customer applies the coupon. You use:
{
"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
}
}
]
}
{
"playerUniqueId": "cust_12345",
"ruleId": 2138,
"transactionId": "txn_001",
"transactionTime": "2024-11-01T12:00:00Z"
}
{
"couponCode": "GB1023",
"redeemEquivalentPoints": 100
}
2. Campaign-Based Coupon Rewards
