Validate Multiple Coupons
Check whether several coupons can be used together by a customer, optionally against the cart they are about to pay for, and reserve them while the order is completed.
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.
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
The same cart is applied to every code incoupons, 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.
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
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 incoupons caused it beyond what the message names.
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.For each coupon: does it exist, does it apply to this cart, and may this customer use it?
Combining coupons
Each coupon carries acombinesWith 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’srules. 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.
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 each coupon object and tells you how all of that coupon’s 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 for any coupon in the list:
- 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 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. SendingcollectionsIds alongside a coupon with no collection rule neither satisfies anything nor triggers anything for that coupon.
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: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.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.
Locking coupons
Setlock 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.
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 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. SendcustomerId 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.
rules and couponRulesLogicalOperator off each coupon 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
4000 rather than a dedicated code. Read the message for the specific reason.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 each 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, and one such coupon in the list is enough to need them. - 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 each coupon’s own restrictions, coupon by coupon. 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. One AND coupon in the list is enough to trigger it. - API v3 cannot satisfy the new restrictions.
POST /api/v3.0/integrations/coupons/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
Coupons validated successfully