Coupons
Use these APIs to generate and redeem coupons for your customers. You can create, apply, and manage coupons as part of your reward or promotional campaigns, ensuring seamless coupon usage for customer
Available APIs
POST - Generate Coupon
The API call creates a coupon based on predefined redemption rules. This endpoint allows for the generation of coupons that align with specific criteria and rewards structures, facilitating promotional efforts and customer engagement.
Security: Requires apikey and secretkey headers.
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
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.
email string
Optional
Customer's email address.
mobile string
Optional
Customer's mobile number.
ruleId integer
Required
The ID of the redemption rule that will be applied to create the coupon. This rule dictates how the coupon will function, such as whether it grants a percentage discount, free shipping, a fixed-amount discount, or a free product. The ruleId
is tied to a predefined redemption rule configured through the Gameball dashboard, ensuring the coupon adheres to the set conditions of that rule. Additionally, the redemption rule determines how many points will be redeemed to generate the coupon.
You can retrieve your configured redemption rules and their associated IDs by using the Redemption Configuration API.
Sample request
Response
application/json
code string
The generated coupon code that the customer will use during checkout or while making a purchase.
startDate string
The date when the coupon becomes valid. If a start date is specified, the coupon cannot be used before this date.
expiryDate string
The date when the coupon expires and can no longer be used. If no expiry date is set, the coupon will be valid indefinitely or until manually disabled.
url string
A URL that directs the customer to a specific page or offer associated with the coupon. This is typically used to promote the coupon or give further instructions.
Example: This URL "https://www.example.com/special-offers/summer2024"
leads to a page where customers can learn more about the Summer 2024 special offer, including how to use the coupon code for discounts or rewards, view eligible products, and understand any restrictions or expiry dates.
pin string
A pin code required in addition to the coupon code, often used for added security or limited access to specific coupons.
Sample Response
POST - Validate Single Coupon
The API call validates a single coupon and checks its eligibility for the customer identified by {code}. This ensures that only valid coupons are applied during checkouts
Security: Requires apiKey header
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
Path Parameters
code string
Required
The coupon code you want to validate.
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.
email string
Optional
Customer's email address.
mobile string
Optional
Customer's mobile number.
lock boolean
Optional
Indicates whether the request is intended to validate the coupon or to lock it for a future redemption.
If
True
, the coupon will be locked, meaning that a hold reference will be returned. This hold reference must then be used when placing an order to redeem the coupon. Locking a coupon ensures that the coupon is reserved and cannot be used by others during the lock session, preventing double usage or conflicts.If
False
(default), the coupon will only be validated to check if it is valid for use, but no lock session will be created or updated, meaning the coupon remains available for others until it is locked and used.
Example: If a customer is browsing and wants to validate whether a coupon is still available and eligible, the lock flag will be set to False
(the default). However, if the customer decides to proceed with the purchase and wants to ensure the coupon is not used by others while finalizing the purchase, the lock flag will be set to True
, and a hold reference will be returned.
lockReference string
Optional
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.
If provided, the existing lock session will be updated with the new coupon(s) validated.
If not provided and the lock flag is
True
, a new session will be created, and a new lock reference will be generated and returned.
Example: If you have already locked a coupon session and need to update or add new coupons to it, you will provide the lockReference
for that session. For instance, if a customer wants to use two coupons, and one is already locked, you will need to provide the lockReference
of the current lock session when validating the second coupon. If you're locking the coupon for the first time, you can leave lockReference
empty, and the system will create a new session and return a new lock reference.
Sample request
Response
application/json
valid boolean
Indicates whether the coupon is valid to be used by the customer or not.
coupon Object
The coupon details
lockReference string
The unique reference code associated with the coupon lock session. This reference is used to ensure that the coupon is reserved for the current session and cannot be used elsewhere until the lock expires or is released.
Example: If a coupon is locked for a transaction, the lockReference
could be something like "74e20fc6bf7a4970ad3c125b1713194f"
.
dateToExpire string
The exact date and time when the coupon lock will expire, after which the coupon will be available for others to use again or for another session.
Example: If the lock is set to expire on October 20, 2024, the dateToExpire
might be "2024-10-20T16:22:00.8249283Z"
, indicating the precise moment the lock is lifted.
Sample Response
POST - Validate Multiple Coupons
The API call validates a list of coupons and checks their eligibility for the customer. This ensures that only valid coupons are applied during checkouts
Security: Requires apiKey header
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
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.
email string
Optional
Customer's email address.
mobile string
Optional
Customer's mobile number.
coupons array
Required
A list of coupon codes to validate.
lock boolean
Optional
Indicates whether the request is intended to validate the coupon or to lock it for a future redemption.
If
True
, the coupon will be locked, meaning that a hold reference will be returned. This hold reference must then be used when placing an order to redeem the coupon. Locking a coupon ensures that the coupon is reserved and cannot be used by others during the lock session, preventing double usage or conflicts.If
False
(default), the coupon will only be validated to check if it is valid for use, but no lock session will be created or updated, meaning the coupon remains available for others until it is locked and used.
Example: If a customer is browsing and wants to validate whether a coupon is still available and eligible, the lock flag will be set to False
(the default). However, if the customer decides to proceed with the purchase and wants to ensure the coupon is not used by others while finalizing the purchase, the lock flag will be set to True
, and a hold reference will be returned.
lockReference string
Optional
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.
If provided, the existing lock session will be updated with the new coupon(s) validated.
If not provided and the lock flag is
True
, a new session will be created, and a new lock reference will be generated and returned.
Example: If you have already locked a coupon session and need to update or add new coupons to it, you will provide the lockReference
for that session. For instance, if a customer wants to use two coupons, and one is already locked, you will need to provide the lockReference
of the current lock session when validating the second coupon. If you're locking the coupon for the first time, you can leave lockReference
empty, and the system will create a new session and return a new lock reference.
Sample request
Response
application/json
valid boolean
Indicates whether the coupons are valid. Example: true
coupons array
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. This reference is used to ensure that the coupon is reserved for the current session and cannot be used elsewhere until the lock expires or is released.
Example: If a coupon is locked for a transaction, the lockReference
could be something like "74e20fc6bf7a4970ad3c125b1713194f"
.
dateToExpire string
The exact date and time when the coupon lock will expire, after which the coupon will be available for others to use again or for another session.
Example: If the lock is set to expire on October 20, 2024, the dateToExpire
might be "2024-10-20T16:22:00.8249283Z"
, indicating the precise moment the lock is lifted.
Sample Response
POST - Burn Coupon
This API is used to burn a coupon associated with a customer. It allows you to deactivate or use up a coupon by providing customer and coupon details.
Security: Requires apikey and secretkey headers.
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
Optional
Customer's email address.
mobile string
Optional
Customer's mobile number.
coupons Array
Optional
List of coupons that need to be burned.
Example: If the customer is using a coupon code while making an order, then you need to burn this code so it is marked as used.
Note: Only one of
coupons
orlockReference
must be provided for the request to proceed.
lockReference string
Optional
Reference used to burn the locked coupons from the validation step.
Example: When you have locked a coupon or group of coupons and need to burn them because the customer has used them, you provide the lock reference for the session to indicate the coupon(s) have been used.
Note: Only one of
coupons
orlockReference
must be provided for the request to proceed.
Sample request
DELETE - Release Coupons
The API call releases the lock on coupons using the specified {lockReference}. This allows the coupons to become available for use again, ensuring flexibility in managing coupon availability and redemption.
Security: Requires apikey and secretkey headers.
Request
Path Parameters
lockReference string
Required
Unique identifier for the previously locked coupons to be available for others to use again or for another session.
Last updated