Skip to main content
POST
cURL
This API validates several coupon codes for one customer in a single call. You can also describe the cart, so every coupon’s rules are checked against what the customer is actually buying, and set lock to true to reserve them all under one lock session. All coupons must pass. The first failure ends the call, and no lock is created — this endpoint never returns a partial result. 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.
To validate a single coupon code, use Validate Single Coupon.
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

The same cart is applied to every code in coupons, and the codes are additionally checked against one another — see Combining coupons. Duplicate codes are rejected outright, so send each code once. A coupon’s rules are only enforced when the request describes a cart, and whether it does is decided separately for each coupon from its own rules — see Eligibility checks. The fields that describe a cart fall into two groups, and the group decides how a rule on that field behaves.
Send lineItems or the flat collection fields, not both. When lineItems is present, the top-level collectionId and collectionsIds are ignored for matching — put every collection on the lines instead. Categories and products are only ever sent on the lines. The cart-level fields are always read from the top of the body.

Line item fields

Only collectionsIds has a flat form. A rule on any other item field — including Category and ProductId — can only be satisfied through lineItems.

Extra data

extra at the top of the body and extra on each line carry free-form data for rules on fields Gameball has no named field for — a payment method, a delivery city, a gift-wrap flag. The rule names the key to read after its prefix: Send each key exactly as it is spelled in the rule. A key that is missing, null, a blank string or an empty list counts as not sent.

Size limits

A request over any limit is rejected with 400.

Example request

cURL

Example response

WINTER25 is an AND coupon, so one single line must be in the winter-24 collection and priced above 50 — the parka is both. FREESHIP has no rules, only a minimum order value of 500, which the 640 total meets.

How validation works

A validate call answers three questions in order. The first failure ends the call — you get one error, never a list, and it does not say which code in coupons caused it beyond what the message names.
1

Is the customer real and active in your Gameball program?

Resolved from customerId, email or mobile.
2

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

Resolved from lockReference.
3

For each coupon: does it 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 rules are checked first.

Combining coupons

Each coupon carries a combinesWith object saying which other discount types it accepts alongside it: orderDiscounts, productDiscounts and shippingDiscounts. When you send several codes in one call, they are checked against one another, and a pair that may not be combined is rejected with 9011. Duplicate codes within coupons are rejected outright — send each code once.

Coupon rules

Every restriction a coupon carries is a rule: the field it reads, an operator, and the values to compare with. Rules are configured on the coupon in the Gameball dashboard, and the validate response returns them on each coupon’s rules. Every coupon in the list is matched against the same cart, each using its own rules and its own operator. rules is null on a coupon configured without rules. Such a coupon is matched against its entitled* lists exactly as before, each list acting as an Equals rule.
On a coupon configured with rules, the entitled* lists hold only the values of its Equals rules on merchant, branch, collection, category and product. A rule with any other operator, and every rule on the other fields, appears in rules only. Read rules for the full picture.

Rule fields

A cart-level rule is checked once, against the order. An item-level rule is checked against each line. TotalItems and TotalUniqueItems are worked out from lineItems, so a coupon with either rule needs the cart sent line by line.

Operators

  • Text is compared case-insensitively, and surrounding whitespace is trimmed. Coupon codes are compared the same way.
  • On a field that holds a list — categories, collectionsIds, tags — Equals is satisfied when any entry matches any value, and NotEquals when no entry matches any of them.
  • Equals with a single number compares numerically, so 100 matches 100.0.
  • The numeric operators need a number on both sides. A value that is not a number never satisfies them.
  • A value the request did not send satisfies only NotExists and IsEmpty.
  • collectionId and collectionsIds are evaluated together as one list.
  • lineItems[].categories are free-text names, not IDs — whatever was typed when the coupon was configured, compared as plain strings.

How rules combine

couponRulesLogicalOperator is returned on each coupon object and tells you how all of that coupon’s rules combine, cart-level and item-level alike.
Under OR, merchant and branch are rules like any other, so they no longer gate the order on their own. An OR coupon with the rules Merchant equals cairo-downtown and Category equals Audio accepts an Audio item bought from any merchant. Use AND when the merchant must always match.
minOrderValue is not a rule. It is set on the coupon’s configuration and is enforced in every mode, including OR — see The minimum order value.

Item-level rules are satisfied line by line

An item-level rule is satisfied when at least one line satisfies it. For a negative operator, that means at least one item lacks the value, not no item has it: a rule Category NotEquals Sale is satisfied by a cart holding one sale item and one full-price item. The flat collection fields describe the whole basket as one line. Sent as "collectionsIds": ["sale", "shoes"], a cart fails a rule Collection NotEquals sale with 9021, because the one line it describes holds sale.

When lineItems is required

Send the cart as lineItems when either of these is true for any coupon in the list:
  • The coupon has a Category or ProductId rule. Categories and products have no top-level field. Without lineItems the rule has no value to read, so it is reported as missing with 9026 or 9030 — or, under OR, simply not satisfied.
  • The coupon is AND and has two or more item-level rules. One single line must satisfy all of them, which the flat collection fields cannot show. The call is rejected with 9032; resend the same cart as lineItems.
  • The coupon has a rule on a field with no flat form — Title, Price, Quantity, Discount, Vendor, Sku, Tags, Weight, ItemExtra.<key>, TotalItems or TotalUniqueItems. Without lineItems the rule has no value to read, so it is reported as missing with 9034 — or, under OR, simply not satisfied.
Because one cart serves the whole list, a single such coupon among the codes is enough to require lineItems for the call. If you are unsure, send lineItems — it answers every case the flat lists do.

Eligibility checks

Whether a call is a cart question or an eligibility question is decided from each coupon’s own rules, not from which fields you happened to send — and it is decided per coupon, so one body can be a cart question for one code in the list and an eligibility question for another. The request describes a cart for a given coupon when it carries data for a field one of that coupon’s rules reads. When it does, every rule that coupon holds is enforced — including ones the request said nothing about. When it does not, that coupon is answered as an eligibility question — “does this customer hold it, and is it live?” — and its rules are reported back instead, so you can discover what to send next. Every other check (active, dates, audience, limits, combinability) runs either way. A field no rule on a coupon reads is ignored for that coupon as though it were never sent. Sending collectionsIds alongside a coupon with no collection rule neither satisfies anything nor triggers anything for that coupon.
The call still fails as a whole on the first coupon that fails. A coupon answered as an eligibility question does not shield the others in the list from having their own rules enforced.
A field you send that a coupon has no rule on is ignored for that coupon.Request data is matched to rules by field. collectionsIds is only ever checked against a Collection rule, merchantId against a Merchant rule, channel against a Channel rule, totalPurchaseAmount against minOrderValue, and so on. When a coupon holds no rule on that field, the field is dropped before matching for that coupon — it cannot satisfy a different rule, and it cannot cause a rejection.Because the list is judged coupon by coupon, the same field can be enforced for one code and discarded for another. Below, WINTER25 has a single rule, on collection, and FREESHIP carries no rules at all:
Request
Neither coupon has a rule on merchant, branch or channel, and neither carries a minOrderValue, so every cart field in that body is discarded. Both coupons are answered as eligibility questions and the call returns valid: true. Add collectionsIds and it becomes a cart question for WINTER25 only — FREESHIP still has nothing to check.
valid: true on an eligibility call means “this customer may use these coupons”, not “these coupons apply to this order”. Read rules, couponRulesLogicalOperator and minOrderValue off each coupon to see what the cart will have to satisfy — or, on a coupon without rules, entitledCollectionIds, entitledCategoryIds, entitledBranchIds, entitledMerchantIds and entitledProductIds. 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 for a coupon with no minOrderValue the amount is ignored outright — it cannot make the call a cart question for that coupon. For one that has a minimum, the amount is enough to describe a cart on its own, and the minimum is then enforced whether or not you sent a value.
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 coupons

Set lock to true to reserve the coupons when they all validate. The response carries one lockReference covering the whole list, plus a dateToExpire, and those coupons cannot be validated-and-locked by another order until the lock expires or is consumed.
A coupon that is already locked still returns valid: true when this request does not lock it. Omit lock, lockReference, and lockDuration — for example, do not send "lock": true, "lockReference": "123", and "lockDuration": 1440. Read isLocked on Get Customer Coupons to see the current lock state.
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 every coupon has passed validation, so a returned lockReference always means all of them were usable by that customer at that moment. If any one coupon fails, nothing is locked.

Locking without a cart

You can lock on an eligibility check. Send customerId and coupons with lock: true and no cart fields: coupons that carry rules still validate — their rules are reported back rather than enforced — and they are still locked against that customer. The lock is built from the coupon codes and the customer alone; the cart plays no part in it.
This is the intended way to reserve coupons before the basket is known. Read rules and couponRulesLogicalOperator off each coupon to see what the cart will have to satisfy.
A cart-less lock does not prove the coupons fit the eventual cart. Rules 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 rule 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.

By status

Customer and request errors

Duplicate codes are currently reported as the generic 4000 rather than a dedicated code. Read the message for the specific reason.

Coupon eligibility errors

All 422.

Rule errors

All 422. A required code means the coupon has a rule on that field and your request sent nothing for it. A not eligible code means you sent it and the value did not satisfy the rule. An OR coupon never returns a required code — not even 9018 or 9024. A rule the cart carries no data for is simply not satisfied. The presence operators (Exists, NotExists, IsEmpty, NotEmpty) never return one either, since a missing value is exactly what they test. 9034 and 9035 cover every field without a code of its own, and the message names the field as you send it: The field reads channel, extra.<key>, title, price, quantity, discount, vendor, sku, tags or weight; itemExtra.<key> for a line’s extra; and lineItems for the TotalItems and TotalUniqueItems rules. Because the message is lower-cased, a key such as extra.paymentMethod reads extra.paymentmethod.

Lock errors

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

Rules with per-rule operators

Coupons now carry rules: each restriction reads one field, with its own operator. Rules can read new cart and line-item fields, and each coupon’s operator now combines all of its rules — merchant and branch included.
couponRulesLogicalOperator changed type. It is now returned as "AND" or "OR", where it used to be 1 or 2. Code that reads it as a number must be updated. null is unchanged.
These apply to every coupon, including ones configured before rules existed, with no change on your side.
  • Read couponRulesLogicalOperator as a string. Expect "AND", "OR" or null.
  • Read rules to see what the cart must satisfy. On a coupon with rules, the entitled* lists show only its Equals rules on merchant, branch, collection, category and product.
  • Send lineItems with the line fields your coupons’ rules read — price, quantity, tags, sku and so on. They have no flat form, and one such coupon in the list is enough to need them.
  • Send channel and extra if your coupons’ rules read them, spelling each extra key exactly as the rule does.
  • Handle 9034 and 9035. Read the message for the field that is missing or did not match.
  • Review OR coupons that rely on a merchant or branch restriction. Under OR it no longer gates the order on its own; switch those coupons to AND.

Cart matching

Before coupon rules, this endpoint was extended from matching a coupon against two things only — the merchant and the collection — to four, and the request gained a line-by-line form of the cart.
These affect calls you are already making, with no change on your side.
Previously any cart field switched on enforcement of every restriction held by every coupon in the list. 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 each coupon’s own restrictions, coupon by coupon. These affect calls you are already making, with no change on your side.
  • Add branchId if your coupons are branch-restricted. There is no other way to satisfy a branch restriction.
  • Send categories and products on lineItems. There is no top-level field for either. When you send lineItems, put collections on the lines too — the top-level collectionId and collectionsIds are silently ignored when lineItems is present.
  • Handle 9032 by retrying with lineItems. It is not a permanent failure; it is a request for more detail about the same cart. One AND coupon in the list is enough to trigger it.
  • API v3 cannot satisfy the new restrictions. POST /api/v3.0/integrations/coupons/validate accepts only merchantId and collectionId, so a coupon restricted by branch, category, product or any of the newer rule fields 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

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.

coupons
string[]
required

A list of coupon codes to validate.

email
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"

channel
string

Cart-level. The sales channel the order is placed through. Read by a coupon's Channel rule.

Maximum string length: 100
Example:

"online"

extra
object

Cart-level. Free-form order data, read by a coupon's Extra. rules. The rule names the key path to read: Extra.paymentMethod reads extra.paymentMethod, and Extra.shipping.city reads the nested extra.shipping.city. Send each key exactly as it is spelled in the rule.

Example:
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
lineItems
object[]

The cart described item by item. Maximum 500 entries. The only way to send categories and products. Required for any rule on a field with no flat form (category, product, title, price, quantity, discount, vendor, sku, tags, weight, extra, and the TotalItems and TotalUniqueItems totals), and for an AND coupon with two or more item-level rules. When lineItems is present, the flat collectionId and collectionsIds fields are ignored for matching.

Maximum array length: 500
totalPurchaseAmount
number

Cart-level. The total value of the purchase the coupon will be applied to. Checked against the coupon's minOrderValue. Sending this field describes a cart only when the coupon carries a minOrderValue; for those coupons it switches on full restriction enforcement, and omitting it is rejected the same way a value below the minimum is.

Response

200 - application/json

Coupons validated successfully

valid
boolean

Indicates whether the coupons are valid.

coupons
object[]

An array containing the details of the coupons that need to be locked or validated in the request.

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.