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>' \
  --header 'secretkey: <api-key>' \
  --data '
{
  "customerId": "<string>",
  "coupons": [
    "<string>"
  ],
  "email": "<string>",
  "mobile": "<string>",
  "lock": true,
  "lockReference": "<string>",
  "lockDuration": 123,
  "merchantId": "<string>",
  "collectionId": "<string>",
  "collectionsIds": [
    "<string>"
  ],
  "totalPurchaseAmount": 123
}
'
{
  "valid": true,
  "coupons": [
    {
      "code": "<string>",
      "type": "shipping",
      "value": 123,
      "usageLimit": 123,
      "limitPerCustomer": 123,
      "startDate": "2023-11-07T05:31:56Z",
      "expiryDate": "2023-11-07T05:31:56Z",
      "capping": 123,
      "minReward": 123,
      "minOrderValue": 123,
      "entitledProductIds": [
        "<string>"
      ],
      "entitledVariantIds": [
        "<string>"
      ],
      "entitledCollectionIds": [
        "<string>"
      ],
      "entitledMerchantIds": [
        "<string>"
      ],
      "combinesWith": {
        "orderDiscounts": true,
        "productDiscounts": true,
        "shippingDiscounts": true
      }
    }
  ],
  "lockReference": "<string>",
  "dateToExpire": "2023-11-07T05:31:56Z"
}
This API validates a list of coupons and checks their eligibility for use by a customer. It also supports a locking feature, where setting the lock flag to True reserves eligible coupons by creating hold references. This ensures that locked coupons cannot be used by others during the lock session, preventing conflicts or double usage. By default, the lock flag is False, allowing only validation without reserving the 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 Channel Merging Guide.
Security: Requires apikey and secretkey headers.

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

This parameter is required only if the coupon is designed to apply to specific merchants.

​
collectionId
string

This parameter is required only if the coupon is configured to apply to specific collections.

​
collectionsIds
string[]

This parameter is required only when the coupon is configured to apply to specific collections.

​
totalPurchaseAmount
number

This parameter represents the total value of the purchase where the coupon will be applied.

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.