Validate Single Coupon

cURL

curl --request POST \
  --url https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --header 'secretkey: <api-key>' \
  --data '
{
  "customerId": "<string>",
  "email": "<string>",
  "mobile": "<string>",
  "lock": true,
  "lockReference": "<string>",
  "lockDuration": 123,
  "merchantId": "<string>",
  "collectionId": "<string>",
  "collectionsIds": [
    "<string>"
  ],
  "totalPurchaseAmount": 123
}
'

const options = {
  method: 'POST',
  headers: {
    apikey: '<api-key>',
    secretkey: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customerId: '<string>',
    email: '<string>',
    mobile: '<string>',
    lock: true,
    lockReference: '<string>',
    lockDuration: 123,
    merchantId: '<string>',
    collectionId: '<string>',
    collectionsIds: ['<string>'],
    totalPurchaseAmount: 123
  })
};

fetch('https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate"

payload = {
    "customerId": "<string>",
    "email": "<string>",
    "mobile": "<string>",
    "lock": True,
    "lockReference": "<string>",
    "lockDuration": 123,
    "merchantId": "<string>",
    "collectionId": "<string>",
    "collectionsIds": ["<string>"],
    "totalPurchaseAmount": 123
}
headers = {
    "apikey": "<api-key>",
    "secretkey": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

using RestSharp;


var options = new RestClientOptions("https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("apikey", "<api-key>");
request.AddHeader("secretkey", "<api-key>");
request.AddJsonBody("{\n  \"customerId\": \"<string>\",\n  \"email\": \"<string>\",\n  \"mobile\": \"<string>\",\n  \"lock\": true,\n  \"lockReference\": \"<string>\",\n  \"lockDuration\": 123,\n  \"merchantId\": \"<string>\",\n  \"collectionId\": \"<string>\",\n  \"collectionsIds\": [\n    \"<string>\"\n  ],\n  \"totalPurchaseAmount\": 123\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate"

	payload := strings.NewReader("{\n  \"customerId\": \"<string>\",\n  \"email\": \"<string>\",\n  \"mobile\": \"<string>\",\n  \"lock\": true,\n  \"lockReference\": \"<string>\",\n  \"lockDuration\": 123,\n  \"merchantId\": \"<string>\",\n  \"collectionId\": \"<string>\",\n  \"collectionsIds\": [\n    \"<string>\"\n  ],\n  \"totalPurchaseAmount\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("apikey", "<api-key>")
	req.Header.Add("secretkey", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customerId' => '<string>',
    'email' => '<string>',
    'mobile' => '<string>',
    'lock' => true,
    'lockReference' => '<string>',
    'lockDuration' => 123,
    'merchantId' => '<string>',
    'collectionId' => '<string>',
    'collectionsIds' => [
        '<string>'
    ],
    'totalPurchaseAmount' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "apikey: <api-key>",
    "secretkey: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate")
  .header("apikey", "<api-key>")
  .header("secretkey", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerId\": \"<string>\",\n  \"email\": \"<string>\",\n  \"mobile\": \"<string>\",\n  \"lock\": true,\n  \"lockReference\": \"<string>\",\n  \"lockDuration\": 123,\n  \"merchantId\": \"<string>\",\n  \"collectionId\": \"<string>\",\n  \"collectionsIds\": [\n    \"<string>\"\n  ],\n  \"totalPurchaseAmount\": 123\n}")
  .asString();

{
  "valid": true,
  "coupon": {
    "code": "<string>",
    "value": 123,
    "usageLimit": 123,
    "limitPerCustomer": 123,
    "startDate": "2023-11-07T05:31:56Z",
    "expiryDate": "2023-11-07T05:31:56Z",
    "capping": 123,
    "minReward": 123,
    "minOrderValue": 123,
    "entitledProductIds": [
      "<string>"
    ],
    "entitledVariantIds": [
      "<string>"
    ],
    "entitledCollectionIds": [
      "<string>"
    ],
    "entitledMerchantIds": [
      "<string>"
    ],
    "combinesWith": {
      "orderDiscounts": true,
      "productDiscounts": true,
      "shippingDiscounts": true
    }
  },
  "lockReference": "<string>",
  "dateToExpire": "2023-11-07T05:31:56Z"
}

POST

api

v4.0

integrations

coupons

{code}

validate

cURL

curl --request POST \
  --url https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --header 'secretkey: <api-key>' \
  --data '
{
  "customerId": "<string>",
  "email": "<string>",
  "mobile": "<string>",
  "lock": true,
  "lockReference": "<string>",
  "lockDuration": 123,
  "merchantId": "<string>",
  "collectionId": "<string>",
  "collectionsIds": [
    "<string>"
  ],
  "totalPurchaseAmount": 123
}
'

const options = {
  method: 'POST',
  headers: {
    apikey: '<api-key>',
    secretkey: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customerId: '<string>',
    email: '<string>',
    mobile: '<string>',
    lock: true,
    lockReference: '<string>',
    lockDuration: 123,
    merchantId: '<string>',
    collectionId: '<string>',
    collectionsIds: ['<string>'],
    totalPurchaseAmount: 123
  })
};

fetch('https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate"

payload = {
    "customerId": "<string>",
    "email": "<string>",
    "mobile": "<string>",
    "lock": True,
    "lockReference": "<string>",
    "lockDuration": 123,
    "merchantId": "<string>",
    "collectionId": "<string>",
    "collectionsIds": ["<string>"],
    "totalPurchaseAmount": 123
}
headers = {
    "apikey": "<api-key>",
    "secretkey": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

using RestSharp;


var options = new RestClientOptions("https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("apikey", "<api-key>");
request.AddHeader("secretkey", "<api-key>");
request.AddJsonBody("{\n  \"customerId\": \"<string>\",\n  \"email\": \"<string>\",\n  \"mobile\": \"<string>\",\n  \"lock\": true,\n  \"lockReference\": \"<string>\",\n  \"lockDuration\": 123,\n  \"merchantId\": \"<string>\",\n  \"collectionId\": \"<string>\",\n  \"collectionsIds\": [\n    \"<string>\"\n  ],\n  \"totalPurchaseAmount\": 123\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate"

	payload := strings.NewReader("{\n  \"customerId\": \"<string>\",\n  \"email\": \"<string>\",\n  \"mobile\": \"<string>\",\n  \"lock\": true,\n  \"lockReference\": \"<string>\",\n  \"lockDuration\": 123,\n  \"merchantId\": \"<string>\",\n  \"collectionId\": \"<string>\",\n  \"collectionsIds\": [\n    \"<string>\"\n  ],\n  \"totalPurchaseAmount\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("apikey", "<api-key>")
	req.Header.Add("secretkey", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customerId' => '<string>',
    'email' => '<string>',
    'mobile' => '<string>',
    'lock' => true,
    'lockReference' => '<string>',
    'lockDuration' => 123,
    'merchantId' => '<string>',
    'collectionId' => '<string>',
    'collectionsIds' => [
        '<string>'
    ],
    'totalPurchaseAmount' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "apikey: <api-key>",
    "secretkey: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.gameball.co/api/v4.0/integrations/coupons/{code}/validate")
  .header("apikey", "<api-key>")
  .header("secretkey", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerId\": \"<string>\",\n  \"email\": \"<string>\",\n  \"mobile\": \"<string>\",\n  \"lock\": true,\n  \"lockReference\": \"<string>\",\n  \"lockDuration\": 123,\n  \"merchantId\": \"<string>\",\n  \"collectionId\": \"<string>\",\n  \"collectionsIds\": [\n    \"<string>\"\n  ],\n  \"totalPurchaseAmount\": 123\n}")
  .asString();

{
  "valid": true,
  "coupon": {
    "code": "<string>",
    "value": 123,
    "usageLimit": 123,
    "limitPerCustomer": 123,
    "startDate": "2023-11-07T05:31:56Z",
    "expiryDate": "2023-11-07T05:31:56Z",
    "capping": 123,
    "minReward": 123,
    "minOrderValue": 123,
    "entitledProductIds": [
      "<string>"
    ],
    "entitledVariantIds": [
      "<string>"
    ],
    "entitledCollectionIds": [
      "<string>"
    ],
    "entitledMerchantIds": [
      "<string>"
    ],
    "combinesWith": {
      "orderDiscounts": true,
      "productDiscounts": true,
      "shippingDiscounts": true
    }
  },
  "lockReference": "<string>",
  "dateToExpire": "2023-11-07T05:31:56Z"
}

This API validates a single coupon identified by {code} and checks its eligibility for use by a customer. It also supports a locking feature, where setting the lock flag to True reserves the coupon by creating a lock reference. This ensures the coupon cannot be used by others during the lock session, preventing conflicts or double usage. By default, the lock flag is False, allowing only validation without reserving the coupon. There are two ways to burn a coupon when placing an order:

Option 1 — Use the coupon code directly in the Order API: Pass the coupon code in the Order API without needing the lock reference. The coupon burns automatically.
Option 2 — Use the lock reference in the Order API: Pass the lockReference from this API into redemption.couponsLockReference in the Order API. The coupon burns automatically — no separate Burn Coupon API call is needed.

If you validate a coupon with lock: true and then call the Release Coupons API before placing the order, the lock is released. If you then try to use the coupon code directly in the Order API, the request will fail. Only release the lock if you are canceling the transaction entirely.

Channel Merging Available
If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball’s channel merging feature helps unify customer profiles. By including the customer’s mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.For more information, head to the Omni-Channel Handling Guide.

Security: Requires apikey and secretkey headers.

Authorizations

apikey

string

header

required

secretkey

string

header

required

Path Parameters

code

string

required

The coupon code you want to validate.

Body

application/json

customerId

string

required

Unique identifier for the customer that you can reference across the customer's whole lifetime. Could be a database ID, random string, email or anything that uniquely identifies the customer.

string

Customer's email address. Required if your account uses email-based channel merging.

mobile

string

Customer's mobile number. Required if your account uses mobile-based channel merging.

lock

boolean

Indicates whether the request is intended to validate the coupon or to lock it for a future redemption.

lockReference

string

Required only if the lock flag is set to True and you need to validate and lock a new or updated list of coupons within an existing lock session.

lockDuration

integer

Represents the number of minutes for which a coupon will be locked if the lock flag is set to True.

merchantId

string

This parameter is required only if the coupon is designed to apply to specific merchants.

collectionId

string

This parameter is required only if the coupon is configured to apply to specific collections.

collectionsIds

string[]

This parameter is required only when the coupon is configured to apply to specific collections.

totalPurchaseAmount

number

This parameter represents the total value of the purchase where the coupon will be applied.

Response

200 - application/json

Coupon validated successfully

valid

boolean

Indicates whether the coupon is valid to be used by the customer or not.

coupon

object

Show child attributes

lockReference

string

The unique reference code associated with the coupon lock session.

dateToExpire

string<date-time>

The exact date and time when the coupon lock will expire.

Generate Coupon

Validate Multiple Coupons

API documentation

Webhooks

Authorizations

Path Parameters

Body

Response