Skip to main content
POST
/
api
/
v4.0
/
integrations
/
coupons
/
validate
cURL
curl --request POST \
  --url https://api.gameball.co/api/v4.0/integrations/coupons/validate \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "customerId": "<string>",
  "coupons": [
    {
      "code": "<string>",
      "pin": "<string>"
    }
  ],
  "email": "<string>",
  "mobile": "<string>",
  "lock": true
}
'
{
  "validCoupons": [
    {
      "code": "<string>",
      "lockReference": "<string>",
      "discountAmount": 123,
      "discountType": "<string>"
    }
  ],
  "invalidCoupons": [
    {
      "code": "<string>",
      "error": "<string>"
    }
  ]
}

​
Validate Multiple Coupons

This API validates multiple coupons at once and checks their eligibility for use by a customer. It supports a locking feature where setting the lock flag to True reserves all valid coupons by creating lock references. This ensures the coupons cannot be used by others during the lock session, preventing conflicts or double usage.
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 Channel Merging Guide.

​
Request Body

​
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.
This is required if your account uses email-based channel merging.
​
mobile
string
Customer’s mobile number.
This is required if your account uses mobile-based channel merging.
​
coupons
array
required
Array of coupon objects to validate.
​
coupons[].code
string
required
The coupon code to validate.
​
coupons[].pin
string
Pin code required for the coupon, if applicable.
​
lock
boolean
Whether to lock valid coupons for exclusive use. When set to true, creates lock references to reserve the coupons.

​
Response

​
validCoupons
array
Array of valid coupon objects with their details.
​
validCoupons[].code
string
The validated coupon code.
​
validCoupons[].lockReference
string
Reference ID for the locked coupon, if locking was requested.
​
validCoupons[].discountAmount
number
The discount amount that will be applied.
​
validCoupons[].discountType
string
Type of discount (fixed, percentage, shipping, etc.).
​
invalidCoupons
array
Array of invalid coupon codes with error messages.
​
invalidCoupons[].code
string
The invalid coupon code.
​
invalidCoupons[].error
string
Error message explaining why the coupon is invalid.

Authorizations

​
apikey
string
header
required

Body

application/json
​
customerId
string
required
​
coupons
object[]
required
​
email
string
​
mobile
string
​
lock
boolean

Response

200 - application/json

Coupons validated successfully

​
validCoupons
object[]
​
invalidCoupons
object[]