Skip to main content
POST
cURL
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’s rules are 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 rules are only enforced when the request describes a cart, and whether it does is decided from that coupon’s 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

The coupon’s operator is AND, so the order must be with cairo-downtown, on the online or app channel, and not paid in cash — and one single line must be an Audio item from Sony priced at 100 or more. The headphones line satisfies all three item rules; the television does not need to.

How validation works

A validate call answers three questions in order. The first failure ends the call — you get one error, never a list.
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

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 rules are checked first.

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 rules. 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 the coupon object and tells you how all of its 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:
  • 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.
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 the coupon’s own rules, not from which fields you happened to send. The request describes a cart when it carries data for a field one of this coupon’s rules reads. When it does, every rule 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 rules 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 no rule reads is ignored as though it were never sent. Sending collectionsIds to a coupon with no collection rule neither satisfies anything nor triggers anything.
A field you send that no rule reads is ignored.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 the coupon holds no rule on that field, the field is dropped before matching — it cannot satisfy a different rule, and it cannot cause a rejection.The coupon below has a single rule, on collection. 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
Response
No collection was sent, and nothing else in the body speaks to a rule 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 rules, couponRulesLogicalOperator and minOrderValue off the response 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 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.
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.
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 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 rules still validates — its rules 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.
This is the intended way to reserve a coupon before the basket is known. Read rules 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. 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

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 the 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.
  • 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 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.
  • 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.
  • 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, 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

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.

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

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 rules it carries and how they combine. On a coupon configured with rules, the entitled* lists hold only the values of its Equals rules on merchant, branch, collection, category and product; read rules for the full picture.

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.