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
Type | Description | Endpoint |
---|---|---|
POST | integrations/coupons/{coupon}/validate | |
POST | integrations/coupons/validate | |
POST | integrations/coupons/{holdReference}/burn | |
DELETE | integrations/coupons/{holdReference}/release |
POST - Validate Single Coupon
mobile
or email
should replace customerId in
case (only if) your account supports channel merging.
Request
Header
Attribute | Type | Required | Description |
---|---|---|---|
| string | Yes | Client API key |
Path Parameters
Attribute | Type | Required | Description |
---|---|---|---|
| string | Yes | Coupon code you want to validate. |
Body
Attribute | Type | Required | Description |
---|---|---|---|
| string | Yes | Unique identifier for the customer in your database.
Could be database ID, random string, email or anything that uniquely identifies the player. |
| string | No | Customer's unique mobile number. (Sent in case your account supports channel merging). |
| string | No | Customer's unique email. (Sent in case your account supports channel merging). |
| 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 |
| 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. |
Response
Parameter | Type | Description |
---|---|---|
| bool | Indicates whether the coupon is valid for redeem or not. |
| object | The details of coupon |
| 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:
|
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:
|
Sample Response
Usage Example
The example shown is a request sent to Gameball to validate a coupon for specific customer.
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
Attribute | Type | Required | Description |
---|---|---|---|
| string | Yes | Client API key |
Body
Attribute | Type | Required | Description |
---|---|---|---|
| string | Yes | Unique identifier for the customer in your database.
Could be database ID, random string, email or anything that uniquely identifies the player. |
| string | No | Customer's unique mobile number. (Sent in case your account supports channel merging). |
| string | No | Customer's unique email. (Sent in case your account supports channel merging). |
| array | Yes | List of coupon codes you need to validate. Every coupon should pass the combine rules with all other coupons. |
| 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 |
| 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. |
Response
Attribute | Type | Description |
---|---|---|
| boolean | Indicates whether the coupon is valid for redeem or not. |
| array | The details of coupons |
| 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:
|
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:
|
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
Attribute | Type | Required | Description |
---|---|---|---|
| string | Yes | Client API key |
| string | Yes | Client Secret key |
Path Parameters
Attribute | Type | Required | Description |
---|---|---|---|
| string | Yes | Hold reference you want to commit and redeem holded coupons |
Usage Example
DELETE - Release Coupons
Request
Header
Attribute | Type | Required | Description |
---|---|---|---|
| string | Yes | Client API key |
| string | Yes | Client Secret key |
Path Parameters
Attribute | Type | Required | Description |
---|---|---|---|
| string | Yes | Hold reference you want to release |