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": "cairo-downtown",
  "branchId": "branch-14",
  "collectionId": "<string>",
  "collectionsIds": [
    "<string>"
  ],
  "categories": [
    "Audio",
    "TV"
  ],
  "productsIds": [
    "<string>"
  ],
  "lineItems": [
    {
      "productId": "<string>",
      "variantId": "<string>",
      "categories": [
        "<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: 'cairo-downtown',
    branchId: 'branch-14',
    collectionId: '<string>',
    collectionsIds: ['<string>'],
    categories: ['Audio', 'TV'],
    productsIds: ['<string>'],
    lineItems: [
      {
        productId: '<string>',
        variantId: '<string>',
        categories: ['<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": "cairo-downtown",
    "branchId": "branch-14",
    "collectionId": "<string>",
    "collectionsIds": ["<string>"],
    "categories": ["Audio", "TV"],
    "productsIds": ["<string>"],
    "lineItems": [
        {
            "productId": "<string>",
            "variantId": "<string>",
            "categories": ["<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\": \"cairo-downtown\",\n  \"branchId\": \"branch-14\",\n  \"collectionId\": \"<string>\",\n  \"collectionsIds\": [\n    \"<string>\"\n  ],\n  \"categories\": [\n    \"Audio\",\n    \"TV\"\n  ],\n  \"productsIds\": [\n    \"<string>\"\n  ],\n  \"lineItems\": [\n    {\n      \"productId\": \"<string>\",\n      \"variantId\": \"<string>\",\n      \"categories\": [\n        \"<string>\"\n      ],\n      \"collectionsIds\": [\n        \"<string>\"\n      ]\n    }\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\": \"cairo-downtown\",\n  \"branchId\": \"branch-14\",\n  \"collectionId\": \"<string>\",\n  \"collectionsIds\": [\n    \"<string>\"\n  ],\n  \"categories\": [\n    \"Audio\",\n    \"TV\"\n  ],\n  \"productsIds\": [\n    \"<string>\"\n  ],\n  \"lineItems\": [\n    {\n      \"productId\": \"<string>\",\n      \"variantId\": \"<string>\",\n      \"categories\": [\n        \"<string>\"\n      ],\n      \"collectionsIds\": [\n        \"<string>\"\n      ]\n    }\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' => 'cairo-downtown',
    'branchId' => 'branch-14',
    'collectionId' => '<string>',
    'collectionsIds' => [
        '<string>'
    ],
    'categories' => [
        'Audio',
        'TV'
    ],
    'productsIds' => [
        '<string>'
    ],
    'lineItems' => [
        [
                'productId' => '<string>',
                'variantId' => '<string>',
                'categories' => [
                                '<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\": \"cairo-downtown\",\n  \"branchId\": \"branch-14\",\n  \"collectionId\": \"<string>\",\n  \"collectionsIds\": [\n    \"<string>\"\n  ],\n  \"categories\": [\n    \"Audio\",\n    \"TV\"\n  ],\n  \"productsIds\": [\n    \"<string>\"\n  ],\n  \"lineItems\": [\n    {\n      \"productId\": \"<string>\",\n      \"variantId\": \"<string>\",\n      \"categories\": [\n        \"<string>\"\n      ],\n      \"collectionsIds\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"totalPurchaseAmount\": 123\n}")
  .asString();

{
  "valid": true,
  "coupon": {
    "code": "<string>",
    "type": "shipping",
    "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>"
    ],
    "entitledBranchIds": [
      "<string>"
    ],
    "entitledCategoryIds": [
      "<string>"
    ],
    "couponRulesLogicalOperator": 1,
    "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": "cairo-downtown",
  "branchId": "branch-14",
  "collectionId": "<string>",
  "collectionsIds": [
    "<string>"
  ],
  "categories": [
    "Audio",
    "TV"
  ],
  "productsIds": [
    "<string>"
  ],
  "lineItems": [
    {
      "productId": "<string>",
      "variantId": "<string>",
      "categories": [
        "<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: 'cairo-downtown',
    branchId: 'branch-14',
    collectionId: '<string>',
    collectionsIds: ['<string>'],
    categories: ['Audio', 'TV'],
    productsIds: ['<string>'],
    lineItems: [
      {
        productId: '<string>',
        variantId: '<string>',
        categories: ['<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": "cairo-downtown",
    "branchId": "branch-14",
    "collectionId": "<string>",
    "collectionsIds": ["<string>"],
    "categories": ["Audio", "TV"],
    "productsIds": ["<string>"],
    "lineItems": [
        {
            "productId": "<string>",
            "variantId": "<string>",
            "categories": ["<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\": \"cairo-downtown\",\n  \"branchId\": \"branch-14\",\n  \"collectionId\": \"<string>\",\n  \"collectionsIds\": [\n    \"<string>\"\n  ],\n  \"categories\": [\n    \"Audio\",\n    \"TV\"\n  ],\n  \"productsIds\": [\n    \"<string>\"\n  ],\n  \"lineItems\": [\n    {\n      \"productId\": \"<string>\",\n      \"variantId\": \"<string>\",\n      \"categories\": [\n        \"<string>\"\n      ],\n      \"collectionsIds\": [\n        \"<string>\"\n      ]\n    }\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\": \"cairo-downtown\",\n  \"branchId\": \"branch-14\",\n  \"collectionId\": \"<string>\",\n  \"collectionsIds\": [\n    \"<string>\"\n  ],\n  \"categories\": [\n    \"Audio\",\n    \"TV\"\n  ],\n  \"productsIds\": [\n    \"<string>\"\n  ],\n  \"lineItems\": [\n    {\n      \"productId\": \"<string>\",\n      \"variantId\": \"<string>\",\n      \"categories\": [\n        \"<string>\"\n      ],\n      \"collectionsIds\": [\n        \"<string>\"\n      ]\n    }\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' => 'cairo-downtown',
    'branchId' => 'branch-14',
    'collectionId' => '<string>',
    'collectionsIds' => [
        '<string>'
    ],
    'categories' => [
        'Audio',
        'TV'
    ],
    'productsIds' => [
        '<string>'
    ],
    'lineItems' => [
        [
                'productId' => '<string>',
                'variantId' => '<string>',
                'categories' => [
                                '<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\": \"cairo-downtown\",\n  \"branchId\": \"branch-14\",\n  \"collectionId\": \"<string>\",\n  \"collectionsIds\": [\n    \"<string>\"\n  ],\n  \"categories\": [\n    \"Audio\",\n    \"TV\"\n  ],\n  \"productsIds\": [\n    \"<string>\"\n  ],\n  \"lineItems\": [\n    {\n      \"productId\": \"<string>\",\n      \"variantId\": \"<string>\",\n      \"categories\": [\n        \"<string>\"\n      ],\n      \"collectionsIds\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"totalPurchaseAmount\": 123\n}")
  .asString();

{
  "valid": true,
  "coupon": {
    "code": "<string>",
    "type": "shipping",
    "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>"
    ],
    "entitledBranchIds": [
      "<string>"
    ],
    "entitledCategoryIds": [
      "<string>"
    ],
    "couponRulesLogicalOperator": 1,
    "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. You can also describe the cart, so the coupon is checked against what the customer is actually buying, and set lock to true to reserve the coupon so it cannot be spent elsewhere while the order is being completed. Available on v4.0 and v4.1. Requires the Gameball Coupon Engine feature on your plan — accounts without it are rejected before any validation runs. 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.

To validate several coupon codes against the same cart in one call, use Validate Multiple Coupons.

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.

Describing the cart

A coupon’s restrictions are only enforced when the request describes a cart, and whether it does is decided from that coupon’s own restrictions — see Eligibility checks. The fields that describe a cart fall into two groups, and the group decides how the restriction behaves.

Group	Fields	Behaviour
Cart-level	`merchantId`, `branchId`, `totalPurchaseAmount`	An order is placed with one merchant at one branch, so these gate the whole basket. They have no per-item form.
Item-level — flat	`collectionId`, `collectionsIds`, `categories`, `productsIds`	What the basket contains, without saying which item contains what.
Item-level — lines	`lineItems[]`	The same cart described item by item.

Send lineItems or the flat lists, not both. When lineItems is present, the top-level collectionId, collectionsIds, categories and productsIds are ignored for matching — put every category, collection and product on the lines instead. The cart-level fields are always read from the top of the body.

variantId on a line item is stored and echoed back on the coupon, but is never evaluated — there is no variant restriction.

Size limits

lineItems accepts at most 500 entries, and any single ID list at most 200 values. A request over either limit is rejected with 400.

Example request

cURL

curl --request POST \
  --url 'https://api.gameball.co/api/v4.0/integrations/coupons/SONYAUDIO/validate' \
  --header 'APIKey: <your-api-key>' \
  --header 'secretkey: <your-secret-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customerId": "omar-9912",
    "lock": true,
    "lockDuration": 30,
    "merchantId": "cairo-downtown",
    "branchId": "branch-14",
    "totalPurchaseAmount": 1450.0,
    "lineItems": [
      {
        "productId": "p-sony-bravia",
        "variantId": "v-55in",
        "categories": ["TV"],
        "collectionsIds": ["electronics"]
      },
      {
        "productId": "p-sony-wh1000",
        "variantId": "v-black",
        "categories": ["Audio"],
        "collectionsIds": ["electronics", "headphones"]
      }
    ]
  }'

Example response

{
  "valid": true,
  "coupon": {
    "code": "sonyaudio",
    "type": "percentage",
    "value": 25.0,
    "usageLimit": -1,
    "limitPerCustomer": 1,
    "startDate": "2026-09-01T00:00:00Z",
    "expiryDate": "2026-12-31T23:59:59Z",
    "capping": 500.0,
    "minReward": null,
    "minOrderValue": 200.0,
    "entitledProductIds": ["p-sony-wh1000", "p-sony-wf1000"],
    "entitledVariantIds": null,
    "entitledCollectionIds": null,
    "entitledMerchantIds": ["cairo-downtown"],
    "entitledBranchIds": null,
    "entitledCategoryIds": ["Audio"],
    "couponRulesLogicalOperator": 1,
    "combinesWith": {
      "orderDiscounts": false,
      "productDiscounts": true,
      "shippingDiscounts": true
    }
  },
  "lockReference": "e7c1f2a9-3b44-4d1e-8f77-2c9ab0d51e63",
  "dateToExpire": "2026-09-16T14:15:00Z"
}

How validation works

A validate call answers three questions in order. The first failure ends the call — you get one error, never a list.

Is the customer real and active in your Gameball program?

Resolved from customerId, email or mobile.

If you referenced an existing lock, is it still usable by this customer?

Resolved from lockReference.

Does the coupon exist, does it apply to this cart, and may this customer use it?

Runs the ordered checks below.

The third question runs these checks in this exact order. The order matters: a coupon that is both expired and wrong for the cart reports the cart problem, because restrictions are checked first.

Order	Check	Error
1	The coupon code exists for your account	`404`, code `4004`
2	The coupon’s restrictions match the cart	See Restriction errors
3	`totalPurchaseAmount` is present and at or above the coupon’s `minOrderValue`	`9017`
4	The coupon is active	`9014`
5	The coupon’s start date has passed	`9011`
6	The coupon has not expired	`9013`
7	The customer is in the coupon’s audience, and the coupon is not assigned to a different customer	`9011`
8	The customer has not hit the coupon’s per-customer limit	`9012`
9	The coupon has not hit its total usage limit	`9012`

How restrictions are matched

A coupon can carry restrictions in five dimensions, plus a minimum order value. The group a restriction belongs to decides how it behaves.

Group	Restrictions	Behaviour
Cart-level	merchant, branch	An order is placed with one merchant at one branch, so these gate the whole basket. They must always match.
Item-level	collection, category, product	These vary from one product to the next, so they are the ones `couponRulesLogicalOperator` arbitrates over.
Amount	`minOrderValue`	Gates the whole basket like a cart-level restriction, but is set on the coupon’s configuration rather than as a rule, so `couponRulesLogicalOperator` never applies to it.

couponRulesLogicalOperator is returned on the coupon object and tells you how its item-level restrictions combine:

Value	Mode	Meaning
`null`	Flat	Every item-level restriction must be satisfied by something in the cart — not necessarily the same item. If the cart carries no data at all for one of them, the call is rejected.
`1`	AND	One single item must satisfy every item-level restriction. Use this for coupons like “25% off Sony audio”, which must not be satisfied by a Sony television plus another brand’s headphones.
`2`	OR	One satisfied restriction is enough. A restriction the cart carries no data for is skipped, never rejected.

Merchant and branch are checked in every mode, including OR. An OR coupon restricted to one merchant still rejects a different merchant, no matter what else in the cart matches.

When lineItems is required

If a coupon has two or more item-level restrictions and couponRulesLogicalOperator is 1 (AND), the flat lists cannot answer the question — they show that the basket holds a Sony item and an audio item, without showing whether one item is both. The call is rejected with code 9032, and you resend the same cart as lineItems. In every other case lineItems is optional.

Matching rules

Coupon codes and restriction values are compared case-insensitively, and surrounding whitespace is trimmed.
Values within a single restriction are alternatives — matching any one of them is enough.
collectionId and collectionsIds are evaluated together as one list.
categories are free-text names, not IDs — whatever was typed when the coupon was configured, compared as plain strings.
variantId on a line item is stored and echoed back but never evaluated.

Eligibility checks

Whether a call is a cart question or an eligibility question is decided from the coupon’s own restrictions, not from which fields you happened to send. The request describes a cart when it carries data for a dimension this coupon restricts on. When it does, every restriction the coupon holds is enforced — including ones the request said nothing about. When it does not, the call is an eligibility question — “does this customer hold this coupon, and is it live?” — and the restrictions are reported back on the coupon instead, so you can discover what to send next. Every other check (active, dates, audience, limits) runs either way. A field the coupon does not restrict on is ignored as though it were never sent. Sending collectionsIds to a coupon with no collection restriction neither satisfies anything nor triggers anything.

Coupon restricts on	Request carries	Outcome
Collection	`customerId` only	Eligibility — `valid: true`
Collection, no `minOrderValue`	`customerId`, `totalPurchaseAmount`	Eligibility — the amount matches no restriction, so it is ignored
Collection	`collectionsIds`	Cart — the collection restriction is enforced
Branch	`collectionsIds`	Eligibility — a collection matches no restriction on this coupon
Merchant, collection, product	`merchantId`, `collectionsIds`	Cart — all three are enforced, so the absent product is rejected with `9030`
Collection, plus `minOrderValue`	`totalPurchaseAmount`	Cart — the amount speaks to the minimum, so the collection restriction is enforced too

A restriction you send that the coupon does not carry is ignored.Request data is matched to restrictions by type. collectionsIds is only ever checked against a collection restriction, merchantId against a merchant restriction, totalPurchaseAmount against minOrderValue, and so on. When the coupon holds no restriction of that type, the field is dropped before matching — it cannot satisfy a different restriction, and it cannot cause a rejection.The coupon below restricts on collection only. Every other field in the request corresponds to nothing on it, so all of them are discarded, the call stays an eligibility check, and it returns valid: true.

Request

{
  "customerId": "sara-1180",
  "merchantId": "cairo-downtown",
  "branchId": "branch-14",
  "categories": ["Outerwear"],
  "productsIds": ["p-parka-navy"],
  "totalPurchaseAmount": 1450.0
}

Response

{
  "valid": true,
  "coupon": {
    "code": "winter25",
    "entitledCollectionIds": ["winter-24"],
    "entitledMerchantIds": null,
    "entitledBranchIds": null,
    "entitledCategoryIds": null,
    "entitledProductIds": null,
    "minOrderValue": null,
    "couponRulesLogicalOperator": null,
    "...": "..."
  },
  "lockReference": null,
  "dateToExpire": null
}

No collection was sent, and nothing else in the body speaks to a restriction this coupon carries — so there is nothing to enforce, and nothing to reject. Send collectionsIds and the same call becomes a cart question.

valid: true on an eligibility call means “this customer may use this coupon”, not “this coupon applies to this order”. Read entitledCollectionIds, entitledCategoryIds, entitledBranchIds, entitledMerchantIds, entitledProductIds, minOrderValue and couponRulesLogicalOperator off the response to see what the cart will have to satisfy, then validate again with those fields populated before you complete the order. That second call can reject a coupon that just came back valid.

The minimum order value

minOrderValue behaves like any other restriction. totalPurchaseAmount is matched against it and nothing else, so on a coupon with no minOrderValue the amount is ignored outright — it cannot make the call a cart question. On a coupon that has one, the amount is enough to describe a cart on its own, and the minimum is then enforced whether or not you sent a value.

Coupon	Request describes a cart	`totalPurchaseAmount`	Result
`minOrderValue: 80`	Yes	`100`	Passes
`minOrderValue: 80`	Yes	`50`	`9017`
`minOrderValue: 80`	Yes	not sent	`9017`
`minOrderValue: 80`	No	not sent	Eligibility — not checked
`minOrderValue: null`	Either	anything	Not checked — there is no minimum to meet

A cart that omits totalPurchaseAmount no longer slips past a coupon that has a minOrderValue. Both “you sent too little” and “you sent nothing” return 9017; read the message to tell them apart.

Locking a coupon

Set lock to true to reserve the coupon when it validates. The response carries a lockReference and a dateToExpire, and the coupon cannot be validated-and-locked by another order until the lock expires or is consumed.

Setting	Effect
`lock: false` (default)	Validation only. `lockReference` and `dateToExpire` come back `null`.
`lock: true`, no `lockReference`	A new lock is created and its reference is returned.
`lock: true` with an existing `lockReference`	The existing lock is reused and the coupon is added to it. If the coupon is already in that lock, the lock is overwritten rather than rejected.
`lockDuration`	Overrides your account’s default lock duration, in minutes. Must be greater than `0` and less than `21600` (15 days).

When you pass an existing lockReference it is checked before anything else, and must be unused, unexpired and belong to the same customer — otherwise the call fails with 9009 or 9010. A lock is only ever created after the coupon has passed validation, so a returned lockReference always means the coupon was usable by that customer at that moment.

Locking without a cart

You can lock on an eligibility check. Send only customerId with lock: true and no cart fields: a coupon that carries restrictions still validates — its restrictions are reported back rather than enforced — and it is still locked against that customer. The lock is built from the coupon code and the customer alone; the cart plays no part in it.

{
  "customerId": "sara-1180",
  "lock": true,
  "lockDuration": 30
}

This is the intended way to reserve a coupon before the basket is known. Read entitledCollectionIds, entitledCategoryIds, entitledBranchIds, entitledMerchantIds, entitledProductIds and couponRulesLogicalOperator off the response to see what the cart will have to satisfy.

A cart-less lock does not prove the coupon fits the eventual cart. Restrictions were never evaluated, and nothing re-evaluates them later — not when the lock is reused, and not when the order is placed. Validate again with the full cart, reusing the same lockReference, before you complete the order: that re-runs the restriction checks against the real basket and keeps the same lock.

Errors

Errors use the standard Gameball error envelope. The message names the specific values that failed, so it is the most useful field for diagnosing a rejection. It is returned in lower case.

{
  "code": 9026,
  "type": "TRANSACTION_ERROR",
  "message": "this coupon requires a valid category to be applied. no category was provided.",
  "documentationUrl": "https://docs.gameball.co/api-reference/coupons/validate-single-coupon",
  "requestId": "3f9c21b8a4d7"
}

By status

Status	When
`400 Bad Request`	Invalid request payload, a missing required field, or a cart over the size limits — more than 500 `lineItems`, or more than 200 values in any single ID list.
`401 Unauthorized`	Missing or invalid API key or secret key.
`404 Not Found`	The customer does not exist, the coupon code does not exist, or the `lockReference` does not exist.
`422 Unprocessable Entity`	The coupon exists but cannot be applied.
`429 Too Many Requests`	Rate limit exceeded.
`500 Internal Server Error`	An unexpected error occurred while validating.

Customer and request errors

Code	Status	Meaning
`7000`	404	The customer was not found for the provided ID, email or mobile.
`3009`	422	The customer exists but is not active in your Gameball program.
`3000`	400	A required field is missing, the coupon code is empty, or the cart exceeded the size limits.
`4004`	404	The coupon code or `lockReference` does not exist.

Coupon eligibility errors

All 422.

Code	Meaning
`9011`	The coupon is not applicable — the customer is outside its audience, it is assigned to a different customer, or it has not started yet.
`9012`	A usage limit was reached — either the coupon’s total limit or this customer’s per-customer limit.
`9013`	The coupon has expired.
`9014`	The coupon is inactive.
`9017`	`totalPurchaseAmount` is below the coupon’s `minOrderValue`, or the request described a cart and omitted it while the coupon has one.

Restriction errors

All 422. A required code means the coupon restricts that dimension and your request described nothing for it. A not eligible code means you described it and the value was not on the coupon’s list.

Code	Restriction	Raised in
`9018`	Merchant — none provided	Every mode
`9019`	Merchant — not eligible	Every mode
`9024`	Branch — none provided	Every mode
`9025`	Branch — not eligible	Every mode
`9020`	Collection — none provided	Flat and AND
`9021`	Collection — not eligible	Flat, AND, and single-restriction OR
`9026`	Category — none provided	Flat and AND
`9027`	Category — not eligible	Flat, AND, and single-restriction OR
`9030`	Product — none provided	Flat and AND
`9031`	Product — not eligible	Flat, AND, and single-restriction OR
`9022`	Several restrictions were checked and none was satisfied	Multi-restriction OR only
`9032`	The coupon must be evaluated against individual cart items — resend with `lineItems`	AND only
`9033`	`lineItems` was sent, every restriction is met somewhere, but no single item meets them all	AND only

An OR coupon never returns a required code for a collection, category or product — a restriction with no cart data is skipped. It can still return 9018 or 9024, because merchant and branch are checked in every mode.

Lock errors

Code	Status	Meaning
`9009`	422	The `lockReference` is invalid, has expired, or belongs to a different customer.
`9010`	422	The `lockReference` has already been used.
`9015`	422	`lockDuration` is negative.
`4000`	400	`lockDuration` is outside the permitted range — it must be greater than 0 and less than 21,600 minutes.

A lockDuration outside the permitted range is currently reported as the generic 4000 rather than the dedicated 9016. Read the message for the specific reason.

What changed

This endpoint previously matched a coupon against two things only: the merchant and the collection. It now matches against four, and the request can describe the cart line by line.

Area	Change
Request	New `branchId`, `categories`, `productsIds` and `lineItems[]`
Response	New `entitledBranchIds`, `entitledCategoryIds` and `couponRulesLogicalOperator`
Response	`entitledProductIds` is no longer limited to a single value
Errors	New `422` codes: `9024`–`9027` and `9030`–`9033`

Behaviour changes on existing requests

These affect calls you are already making, with no change on your side.

What	Before	Now
A coupon restricted by branch, category or product	The restriction was stored but not enforced	Enforced
A coupon with two or more restrictions, where your cart described only one of them	Accepted	Rejected with the matching required code
A coupon restricted by merchant, with `couponRulesLogicalOperator` = `2` (OR)	The wrong merchant could still pass if another restriction matched	The merchant must always match
Sending `collectionId` and `collectionsIds` together	Only `collectionsIds` was evaluated	Both are evaluated as one list
A validate call sending no cart fields at all	Rejected with `9018`	Returns `200` with the coupon’s restrictions attached

Restriction matching is now decided per coupon

Previously any cart field switched on enforcement of every restriction the coupon held. A body carrying nothing but customerId and totalPurchaseAmount was enough to have a collection-restricted coupon rejected with 9020, for a dimension the caller never meant to describe.Enforcement is now decided from the coupon’s own restrictions. These affect calls you are already making, with no change on your side.

What	Before	Now
A cart field the coupon does not restrict on	Switched on enforcement of the coupon’s other restrictions	Ignored as though it were never sent
`totalPurchaseAmount` alone, coupon has no `minOrderValue`	Enforced every restriction; a restricted coupon was rejected	Eligibility check — `valid: true` with restrictions attached
`totalPurchaseAmount` alone, coupon has a `minOrderValue`	Enforced every restriction	Unchanged — the amount speaks to the minimum, so it describes a cart
A cart describing some of a coupon’s restrictions	Enforced all of them	Unchanged — the missing ones still return their required code
A cart omitting `totalPurchaseAmount`, coupon has a `minOrderValue`	Accepted — the minimum was skipped	Rejected with `9017`

Error precedence, the couponRulesLogicalOperator modes and every error code are unchanged.

Migration notes

Add branchId if your coupons are branch-restricted. There is no other way to satisfy a branch restriction.
Choose between lineItems and the flat lists. Sending both is not an error, but the flat lists are silently ignored. If you are unsure, send lineItems — it answers every case the flat lists do, plus the AND case they cannot.
Handle 9032 by retrying with lineItems. It is not a permanent failure; it is a request for more detail about the same cart.
API v3 cannot satisfy the new restrictions. POST /api/v3.0/integrations/coupons/{code}/validate accepts only merchantId and collectionId, so a coupon restricted by branch, category or product is rejected with no field available to fix it. Move to v4 before configuring those restrictions.

Authorizations

apikey

string

header

required

secretkey

string

header

required

Path Parameters

code

string

required

The coupon code you want to validate. Compared case-insensitively.

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

Cart-level. The merchant the order is placed with. Required if the coupon is restricted to specific merchants.

Example:

"cairo-downtown"

branchId

string

Cart-level. The branch or outlet the order is placed at. Required if the coupon is restricted to specific branches. There is no plural or per-item form.

Example:

"branch-14"

collectionId

string

Item-level. A collection the basket touches. Evaluated together with collectionsIds as a single list. Ignored when lineItems is present.

collectionsIds

string[]

Item-level. Every collection the basket touches. Maximum 200 values. Ignored when lineItems is present.

Maximum array length: 200

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

A coupon as returned by the validate endpoints, including the restrictions it carries and how they combine.

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.

API documentation

Webhooks

Describing the cart

Size limits

Example request

Example response

How validation works

How restrictions are matched

When lineItems is required

Matching rules

Eligibility checks

The minimum order value

Locking a coupon

Locking without a cart

Errors

By status

Customer and request errors

Coupon eligibility errors

Restriction errors

Lock errors

What changed

Authorizations

Path Parameters

Body

Response

​Describing the cart

​Size limits

​Example request

​Example response

​How validation works

​How restrictions are matched

​When lineItems is required

​Matching rules

​Eligibility checks

​The minimum order value

​Locking a coupon

​Locking without a cart

​Errors

​By status

​Customer and request errors

​Coupon eligibility errors

​Restriction errors

​Lock errors

​What changed

Authorizations

Path Parameters

Body

Response

Describing the cart

Size limits

Example request

Example response

How validation works

How restrictions are matched

When lineItems is required

Matching rules

Eligibility checks

The minimum order value

Locking a coupon

Locking without a cart

Errors

By status

Customer and request errors

Coupon eligibility errors

Restriction errors

Lock errors

What changed