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
Last updated
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
Last updated
Available APIs
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.
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.
Note: This is required if your account uses email-based channel merging.
mobile string Optional
Customer's mobile number.
Note: This is required if your account uses mobile-based channel merging.
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.
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.
This API validates a single coupon identified by {code} and checks its eligibility for use by a customer. It also supports a locking feature, where setting the lock flag to True reserves the coupon by creating a lock reference. This ensures the coupon 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 coupon.
Security: Requires apiKey header
code string Required
The coupon code you want to validate.
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.
Note: This is required if your account uses email-based channel merging.
mobile string Optional
Customer's mobile number.
Note: This is required if your account uses mobile-based channel merging.
lock boolean Optional
Indicates whether the request is intended to validate the coupon or to lock it for a future redemption.
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.
lockDurationinteger Optional
Represents the number of minutes for which a coupon will be locked if the lock flag is set to True. This duration determines how long the coupon remains reserved, preventing others from using it during this period.
If the lockDuration attribute is not included in the request body, the system will automatically apply the fallback duration.
The fallback duration is determined by the configured lock duration set in the Gameball dashboard.
If no configuration is set in the dashboard, the final fallback is the default duration of 120 minutes.
This behavior ensures flexibility while maintaining consistency. Businesses can configure specific lock durations to suit their unique use cases, such as shorter locks for flash sales or longer locks for premium customers. At the same time, the system ensures that a global default is always in place as a reliable backup, allowing seamless operation even when no specific configuration is provided.
By enabling both custom configurations and a fallback mechanism, this approach allows businesses to adapt to varied scenarios while maintaining control over coupon usage and reservation policies
merchantIdstring Optional
This parameter is required only if the coupon is designed to apply to specific merchants. Use it to validate the coupon against the intended merchant, ensuring it is redeemed within the correct merchant context.
collectionId string Optional
This parameter is required only if the coupon is configured to apply to specific collections. Use it to validate the coupon against the intended collection, ensuring it is redeemed for eligible items within those collections.
totalPurchaseAmountdouble Optional
This parameter represents the total value of the purchase where the coupon will be applied. It is used to validate that the purchase amount exceeds the minimum order value configured during coupon creation. This ensures that the coupon eligibility criteria are met and encourages customers to meet the required spend threshold.
application/json
valid boolean
Indicates whether the coupon is valid to be used by the customer or not.
coupon Object
The coupon details
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.
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.
Security: Requires apiKey header
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.
Note: This is required if your account uses email-based channel merging.
mobile string Optional
Customer's mobile number.
Note: This is required if your account uses mobile-based channel merging.
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 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.
lockDurationinteger Optional
Represents the number of minutes for which a coupon will be locked if the lock flag is set to True. This duration determines how long the coupon remains reserved, preventing others from using it during this period.
If the lockDuration attribute is not included in the request body, the system will automatically apply the fallback duration.
The fallback duration is determined by the configured lock duration set in the Gameball dashboard.
If no configuration is set in the dashboard, the final fallback is the default duration of 120 minutes.
This behavior ensures flexibility while maintaining consistency. Businesses can configure specific lock durations to suit their unique use cases, such as shorter locks for flash sales or longer locks for premium customers. At the same time, the system ensures that a global default is always in place as a reliable backup, allowing seamless operation even when no specific configuration is provided.
By enabling both custom configurations and a fallback mechanism, this approach allows businesses to adapt to varied scenarios while maintaining control over coupon usage and reservation policies
merchantIdstring Optional
This parameter is required only if the coupon is designed to apply to specific merchants. Use it to validate the coupon against the intended merchant, ensuring it is redeemed within the correct merchant context.
collectionId string Optional
This parameter is required only if the coupon is configured to apply to specific collections. Use it to validate the coupon against the intended collection, ensuring it is redeemed for eligible items within those collections.
totalPurchaseAmountdouble Optional
This parameter represents the total value of the purchase where the coupon will be applied. It is used to validate that the purchase amount exceeds the minimum order value configured during coupon creation. This ensures that the coupon eligibility criteria are met and encourages customers to meet the required spend threshold.
application/json
valid boolean
Indicates whether the coupons are valid.
Example: true if the coupon is eligible for use by the customer, and false if the coupon cannot be applied to the customer's order.
coupons arrayAn array containing the details of the coupons that need to be locked or validated in the request.
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.
This API processes the use of one or more coupons associated with a customer in Gameball. By providing customer details and a list of coupons, this endpoint marks the coupons as redeemed, completing the transaction. Optionally, a lockReference can be included to burn previously locked coupons.
Security: Requires apikey and secretkey headers.
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.
Note: This is required if your account uses email-based channel merging.
mobile string Optional
Customer's mobile number.
Note: This is required if your account uses mobile-based channel merging.
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
couponsorlockReferencemust 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
couponsorlockReferencemust be provided for the request to proceed.
This API releases the lock on coupons identified by the provided {lockReference} in Gameball. Once released, the coupons become available for use again, offering flexibility in managing coupon availability and redemption.
Security: Requires apikey and secretkey headers.
lockReference string Required
Unique identifier for the previously locked coupons to be available for others to use again or for another session.
The API call applies a predefined automatic coupon that aligns with specific promotional criteria and reward structures. It enables seamless integration with promotional campaigns, ensuring coupons are issued based on predefined eligibility conditions, enhancing customer engagement and marketing efforts.
Security: Requires apiKey header.
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.
Note: This is required if your account uses email-based channel merging.
mobile string Optional
Customer's mobile number.
Note: This is required if your account uses mobile-based channel merging.
cartIdstring Required
Identifier for the shopping cart associated with the order.
totalPrice float Optional
The total cost of the order, including all item prices, shipping, taxes, and tips. This value does not account for any discounts or coupons applied and is not used for calculations in Gameball; it is solely saved as historical data linked to the order. Must be a positive value.
Example: A customer purchases items worth $120, including taxes and shipping. Even if a $20 coupon is applied, the totalPrice remains $120 as it represents the original cost of the order before any discounts are applied.
totalShipping float Optional
totalShippingCost: The total shipping cost associated with the order. This should be included when a Free Shipping promotion is configured in your account, enabling the system to calculate and apply the appropriate discount to the cart.
lineItems array Optional
An array containing details about each product in the order. If not provided, the calculation will only consider the total order values.
merchant object Optional
This object contains details about the specific merchant involved in the transaction, which is particularly important for businesses managing multiple merchants or branches under the same Gameball account. This object can provide identifying information about both the main merchant and any associated branch where the transaction took place.
application/json
isApplied boolean
A boolean indicating whether a coupon was successfully applied to the order (true if applied, false otherwise).
couponNamestring
The name of the applied coupon.
discountAmountnumber
The total discount value applied to the order.
discountTypestring
Type of the coupon, such as fixed amount, percentage discount, free shipping, or product-specific coupon.Possible Values :
shipping
fixed
percentage
product
buyXgetY
discountedItemsarray
A list of affected items, detailing their price, quantity, and applied discount.
You can retrieve your configured redemption rules and their associated IDs by using the .
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 .
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 using the . Locking a coupon ensures that the coupon is reserved and cannot be used by others during the lock session, preventing double usage or conflicts.
Alternatively, you can use the coupon code directly when placing an order instead of the hold reference. For more details, refer to the .
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.This lock reference is essential for linking the coupon to the order, and it must be included in the request to apply the coupon to the customer's final order.
Example: If a coupon is locked for a transaction, the lockReference could be something like "74e20fc6bf7a4970ad3c125b1713194f".
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 .
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 using the . Locking a coupon ensures that the coupon is reserved and cannot be used by others during the lock session, preventing double usage or conflicts.
Alternatively, you can use the coupon code directly when placing an order instead of the hold reference. For more details, refer to the .
lockReference string
The unique reference code associated with the coupon lock session. This reference ensures that the coupon is reserved exclusively for the current session and cannot be used elsewhere until the lock expires or is released. This lock reference is essential for linking the coupon to the order, and it must be included in the request to apply the coupon to the customer's final order.
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 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 .