Validate Single Coupon
Check whether one coupon can be used by a customer, optionally against the cart they are about to pay for, and reserve it while the order is completed.
{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
lockReferencefrom this API intoredemption.couponsLockReferencein the Order API. The coupon burns automatically — no separate Burn Coupon API call is needed.
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.
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.Line item fields
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:
null, a blank string or an empty list counts as not sent.
Size limits
400.
Example request
Example response
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.Is the customer real and active in your Gameball program?
customerId, email or mobile.If you referenced an existing lock, is it still usable by this customer?
lockReference.Does the coupon exist, does it apply to this cart, and may this customer use it?
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 onrules.
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.
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
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—Equalsis satisfied when any entry matches any value, andNotEqualswhen no entry matches any of them. Equalswith a single number compares numerically, so100matches100.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
NotExistsandIsEmpty. collectionIdandcollectionsIdsare evaluated together as one list.lineItems[].categoriesare 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.
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 NotEqualsSale 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 aslineItems when either of these is true:
- The coupon has a
CategoryorProductIdrule. Categories and products have no top-level field. WithoutlineItemsthe rule has no value to read, so it is reported as missing with9026or9030— or, underOR, simply not satisfied. - The coupon is
ANDand 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 with9032; resend the same cart aslineItems. - The coupon has a rule on a field with no flat form —
Title,Price,Quantity,Discount,Vendor,Sku,Tags,Weight,ItemExtra.<key>,TotalItemsorTotalUniqueItems. WithoutlineItemsthe rule has no value to read, so it is reported as missing with9034— or, underOR, simply not satisfied.
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. SendingcollectionsIds to a coupon with no collection rule neither satisfies anything nor triggers anything.
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.collectionsIds and the same call becomes a cart question.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.
Locking a coupon
Setlock 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.
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.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 onlycustomerId 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.
rules and couponRulesLogicalOperator off the response to see what the cart will have to satisfy.
Errors
Errors use the standard Gameball error envelope. Themessage 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
All422.
Rule errors
All422. 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.
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:
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
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.Behaviour changes on existing requests
Behaviour changes on existing requests
Migration notes
Migration notes
- Read
couponRulesLogicalOperatoras a string. Expect"AND","OR"ornull. - Read
rulesto see what the cart must satisfy. On a coupon with rules, theentitled*lists show only itsEqualsrules on merchant, branch, collection, category and product. - Send
lineItemswith the line fields your coupons’ rules read —price,quantity,tags,skuand so on. They have no flat form. - Send
channelandextraif your coupons’ rules read them, spelling eachextrakey exactly as the rule does. - Handle
9034and9035. Read themessagefor the field that is missing or did not match. - Review
ORcoupons that rely on a merchant or branch restriction. UnderORit no longer gates the order on its own; switch those coupons toAND.
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.Behaviour changes on existing requests
Behaviour changes on existing requests
Restriction matching is now decided per coupon
Restriction matching is now decided per coupon
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.Migration notes
Migration notes
- Add
branchIdif 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 sendlineItems, put collections on the lines too — the top-levelcollectionIdandcollectionsIdsare silently ignored whenlineItemsis present. - Handle
9032by retrying withlineItems. 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}/validateaccepts onlymerchantIdandcollectionId, 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.
Body
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.
500Cart-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
Coupon validated successfully