Coupons
The Coupons API can be used to validate individual or multiple coupon codes, create and manage hold coupons for future use, burn held coupons, and release held coupons when no longer needed.
This endpoint is only available for our GURU clients only 👑
Available Endpoints
POST - Validate Single Coupon
mobile
or email
should replace customerId in
case (only if) your account supports channel merging.
Request
Header
APIKey
string
Yes
Client API key
Path Parameters
coupon
string
Yes
Coupon code you want to validate.
Body
customerId
string
Yes
Unique identifier for the customer in your database.
Could be database ID, random string, email or anything that uniquely identifies the player.
mobile
string
No
Customer's unique mobile number. (Sent in case your account supports channel merging).
email
string
No
Customer's unique email. (Sent in case your account supports channel merging).
lock
boolean
Yes
Indicates whether the request is just to validate the coupon or it should be locked to start a new hold session. If True, then a hold reference is returned, and that hold reference should be used whenever the order is placed to redeem that coupon, If False, the coupon is just validated but the hold session won’t be updated/created
holdReference
string
No
Required only if the lock flag is True and you need to validate and hold a new (possibly updated) list of coupons to an existing session. If not passed and the lock flag is True, a new session will be created and a new hold reference will be generated and returned.
collectionId
string
No
Required only if you're using a coupon that applies on a specific collection(s), and you wish to validate this coupon against the intended Collection ID.
merchantId
string
No
Required only if you're using a coupon that applies on a specific merchant(s) and you wish to validate this coupon against the intended Merchant ID
Response
valid
bool
Indicates whether the coupon is valid for redeem or not.
coupon
object
The details of coupon
holdReference
string
The hold reference (in case the request was sent with a True lock flag)
Note: HoldReference should be saved and sent along with the order API or Redeem API to mark these coupons as used.
Coupon Object
Attribute
Type
Required
Description
code
string
Yes
The unique code for the coupon.
type
string/enum
Yes
Indicates the type of the coupon, the value of the string can be one of the following:
percentage
fixed
value
number
Yes
The value that the coupon can deduct.
usageLimit
number
Yes
The maximum number of usage for this coupon. null means unlimited. By default unlimited.
limitPerCustomer
number
Yes
The maximum number of usage per customer for this coupon. null means unlimited. By default unlimited.
startDate
date/time
No
The start date of the coupon to be valid. By default the coupon starts from the creation date.
expiryDate
date/time
No
The date that the coupon will expire at. By default the coupon will never expire.
capping
number
No
The maximum discount value for percentage coupons
minOrderValue
number
No
The minimum monetary value for the order to apply the coupon.
productId
string
No
The product id that the coupon are valid for
variantId
string
No
The variant id that the coupon are valid for
collections
array
No
The list of collections that the coupon are valid for
combinesWith
object
No
An object that determines whether specific types of discounts can be combined and consists of three boolean values:
ShippingDiscounts
ProductDiscounts
OrderDiscounts
Sample Response
Usage Example (1)
The example shown is a request sent to Gameball to validate a coupon for specific customer.
Usage Example (2)
The example shown is a request sent to Gameball to validate a coupon for specific customer on a specific collectionId and specific merchantId.
POST - Validate Multiple Coupon
mobile
or email
should replace customerId
in
case (only if) your account supports channel merging.
Please note that coupons must allow combination to use validate them together.
Request
Header
APIKey
string
Yes
Client API key
Body
customerId
string
Yes
Unique identifier for the customer in your database.
Could be database ID, random string, email or anything that uniquely identifies the player.
mobile
string
No
Customer's unique mobile number. (Sent in case your account supports channel merging).
email
string
No
Customer's unique email. (Sent in case your account supports channel merging).
coupons
array
Yes
List of coupon codes you need to validate. Every coupon should pass the combine rules with all other coupons.
lock
boolean
Yes
Indicates whether the request is just to validate the coupons or it should be locked to start a new hold session. If True, then a hold reference is returned, and that hold reference should be used whenever the order is placed to redeem these coupons, If False, the coupons are just validated but the hold session won’t be updated/created
holdReference
string
No
Required only if the lock flag is True and you need to validate and hold a new (possibly updated) list of coupons to an existing session. If not passed and the lock flag is True, a new session will be created and a new hold reference will be generated and returned.
collectionId
string
No
Required only if you're using a coupon that applies on a specific collection(s), and you wish to validate this coupon against the intended Collection ID.
merchantId
string
No
Required only if you're using a coupon that applies on a specific merchant(s) and you wish to validate this coupon against the intended Merchant ID
Response
valid
boolean
Indicates whether the coupon is valid for redeem or not.
coupons
array
The details of coupons
holdReference
string
The hold reference (in case the request was sent with a True lock flag) Note: HoldReference should be saved and sent along with the order API or Redeem API to mark these coupons as used.
Coupon Object
Attribute
Type
Required
Description
code
string
Yes
The unique code for the coupon.
type
string/enum
Yes
Indicates the type of the coupon, the value of the string can be one of the following:
percentage
fixed
value
number
Yes
The value that the coupon can deduct.
usageLimit
number
Yes
The maximum number of usage for this coupon. null means unlimited. By default unlimited.
limitPerCustomer
number
Yes
The maximum number of usage per customer for this coupon. null means unlimited. By default unlimited.
startDate
date/time
No
The start date of the coupon to be valid. By default the coupon starts from the creation date.
expiryDate
date/time
No
The date that the coupon will expire at. By default the coupon will never expire.
capping
number
No
The maximum discount value for percentage coupons
minOrderValue
number
No
The minimum monetary value for the order to apply the coupon.
productId
string
No
The product id that the coupon are valid for
variantId
string
No
The variant id that the coupon are valid for
collections
array
No
The list of collections that the coupon are valid for
combinesWith
object
No
An object that determines whether specific types of discounts can be combined and consists of three boolean values:
ShippingDiscounts
ProductDiscounts
OrderDiscounts
Sample Response
Usage Example
The example shown is a request sent to Gameball to validate multiple coupons for specific customer.
POST - Burn Coupons
Note: If the coupon code has already been sent and used via the Order API, you do not need to use this API for burning the coupons. The Order API will handle the processing and redemption of the coupons automatically, ensuring the coupon is burned.
Request
Headers
APIKey
string
Yes
Client API key
SecretKey
string
Yes
Client Secret key
Path Parameters
holdReference
string
Yes
Hold reference you want to commit and redeem holded coupons
Usage Example
DELETE - Release Coupons
Request
Header
APIKey
string
Yes
Client API key
SecretKey
string
Yes
Client Secret key
Path Parameters
holdReference
string
Yes
Hold reference you want to release
Usage Example
Last updated