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	Validate Single Coupon	integrations/coupons/{coupon}/validate
POST	Validate Multiple Coupons	integrations/coupons/validate
POST	Burn Coupons	integrations/coupons/{holdReference}/burn
DELETE	Release Coupons	integrations/coupons/{holdReference}/release

POST - Validate Single Coupon

https://api.gameball.co/api/v3.0/integrations/coupons/{coupon}/validate

mobile or email should replace customerId in case (only if) your account supports channel merging.

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key

Path Parameters

Attribute	Type	Required	Description
coupon	string	Yes	Coupon code you want to validate.

Body

Attribute	Type	Required	Description
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.

Response

Parameter	Type	Description
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

{
    "valid": true,
    "coupon": {
        "code": "teg17zlvne",
        "type": "percentage",
        "value": 10.0,
        "usageLimit": 1000,
        "limitPerCustomer": 10,
        "startDate": null,
        "expiryDate": null,
        "capping": 0.0,
        "minOrderValue": 0.0,
        "productId": null,
        "variantId": null,
        "collections": null,
        "combinesWith": {
            "orderDiscounts": true,
            "productDiscounts": false,
            "shippingDiscounts": false
        }
    },
    "holdReference": "b07ae032db4e4e73b3b42019922f00aa",
    "dateToExpire": "2024-08-01T13:32:52.8353324Z"
}

Usage Example

The example shown is a request sent to Gameball to validate a coupon for specific customer.

cURL

curl -X POST "https://api.gameball.co/api/v3.0/integrations/coupons/{coupon}/validate" \
-H "APIKey: 807b041b7d35425988e354e1f6bce186" \
-H "SecretKey: klmb041b7d354259l3u4ft35e1q2r3703" \
-H "Content-Type: application/json" \
-d '{
  "customerId": "player456",
  "mobile": "010XXXXXXXX",
  "email": "[e-mail]",
  "lock": true,
  "holdReference": null
}'

POST - Validate Multiple Coupon

https://api.gameball.co/api/v3.0/integrations/coupons/validate

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
APIKey	string	Yes	Client API key

Body

Attribute	Type	Required	Description
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.

Response

Attribute	Type	Description
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

{
    "valid": true,
    "coupons": [
        {
            "code": "teg17zlvne",
            "type": "percentage",
            "value": 10.0,
            "usageLimit": 1000,
            "limitPerCustomer": 10,
            "startDate": null,
            "expiryDate": null,
            "capping": 0.0,
            "minOrderValue": 0.0,
            "productId": null,
            "variantId": null,
            "collections": null,
            "combinesWith": {
                "orderDiscounts": true,
                "productDiscounts": false,
                "shippingDiscounts": false
            }
        },
        {
            "code": "4ik4o6rsjp",
            "type": "fixed",
            "value": 20.0,
            "usageLimit": 10,
            "limitPerCustomer": 1,
            "startDate": null,
            "expiryDate": "2040-12-31T21:59:00Z",
            "capping": 0.0,
            "minOrderValue": 100.0,
            "productId": null,
            "variantId": null,
            "collections": null,
            "combinesWith": {
                "orderDiscounts": true,
                "productDiscounts": false,
                "shippingDiscounts": false
            }
        }
    ],
    "holdReference": "baf808b3d0554a81b32b2ff500f52c79",
    "dateToExpire": "2024-08-01T13:29:41.905912Z"
}

Usage Example

The example shown is a request sent to Gameball to validate multiple coupons for specific customer.

cURL

curl -X POST "https://api.gameball.co/api/v3.0/integrations/coupons/validate" \
-H "APIKey: 807b041b7d35425988e354e1f6bce186" \
-H "Content-Type: application/json" \
-d '{
  "customerId": "player456",
  "mobile": "010XXXXXXXX",
  "email": "[e-mail]",
  "coupons": ["coupon_code_1", "coupon_code_2"],
  "lock": true,
  "holdReference": null
}'

POST - Burn Coupons

https://api.gameball.co/api/v3.0/integrations/coupons/{holdReference}/burn

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
APIKey	string	Yes	Client API key
SecretKey	string	Yes	Client Secret key

Path Parameters

Attribute	Type	Required	Description
holdReference	string	Yes	Hold reference you want to commit and redeem holded coupons

Usage Example

cURL

curl -X POST "https://api.gameball.co/api/v3.0/integrations/coupons/{holdReference}/burn" \
-H "APIKey: 807b041b7d35425988e354e1f6bce186" \
-H "SecretKey: klmb041b7d354259l3u4ft35e1q2r3703"

DELETE - Release Coupons

https://api.gameball.co/api/v3.0/integrations/coupons/{holdReference}/release

Request

Header

Attribute	Type	Required	Description
APIKey	string	Yes	Client API key
SecretKey	string	Yes	Client Secret key

Path Parameters

Attribute	Type	Required	Description
holdReference	string	Yes	Hold reference you want to release

Usage Example

cURL

curl -X DELETE "https://api.gameball.co/api/v3.0/integrations/coupons/{holdReference}/release" \
-H "APIKey: 807b041b7d35425988e354e1f6bce186" \
-H "SecretKey: klmb041b7d354259l3u4ft35e1q2r3703"