v4.0

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

https://api.gameball.co/api/v4/integrations/coupons/predefined

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.

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.

You can retrieve your configured redemption rules and their associated IDs by using the Redemption Configuration API.

Sample request

{
  "customerId": "h5jxz",
  "mobile": "+1234567890",
  "email": "alex.jones@example.com",
  "ruleId": 2182
}

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

{
  "code": "7wagbk72a4",
  "startDate": "2024-10-16T08:13:00.0000Z",
  "expiryDate": "2027-10-16T08:13:00.0000Z",
  "url": "https://example.com/coupons/7wagbk72a4",
  "pin": "1234",
}

POST - Validate Single Coupon

https://api.gameball.co/api/v4/integrations/coupons/{code}/validate

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

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.

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 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.

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.

Sample request

{
  "customerId": "h5jxz",
  "mobile": "+1234567890",
  "email": "alex.jones@example.com",
  "lock": true,
  "lockReference": null
}

Response

application/json

valid boolean Indicates whether the coupon is valid to be used by the customer or not.

coupon Object The coupon details

Coupon Object

code string The generated coupon code that the customer will use. Example: If a coupon code like "7wagbk72a4" is generated for a customer, it can be used during checkout to apply the relevant discount or offer.

type string Type of the coupon, such as fixed amount, percentage discount, free shipping, or product-specific coupon.Possible Values :

  • shipping

  • fixed

  • percentage

  • product

value number The monetary value or percentage value of the coupon, depending on its type. Example: If a coupon provides a $100 discount, the value will be 100.

usageLimit number The total number of times the coupon can be used across all customers. Example: If a coupon can only be used once, the usageLimit will be set to 1, indicating that it cannot be reused after the first use.

limitPerCustomer number The number of times a single customer can use the coupon. Example: If each customer can only use the coupon one time, the limitPerCustomer will be set to 1, ensuring the coupon can only be redeemed once per customer.

startDate string The date and time when the coupon becomes valid and can be used. Example: If the coupon becomes valid on October 17, 2024, the startDate will be "2024-10-17T08:22:00.0000Z".

expiryDate string The date and time when the coupon will expire and no longer be valid. Example: If the coupon expires on October 17, 2027, the expiryDate will be "2027-10-17T08:22:00.0000Z".

capping number The maximum discount or value cap that the coupon can offer, even if the discount calculation exceeds this value.

Example: If the maximum discount for the coupon is capped at $400, the capping will be set to 400, meaning the discount will not exceed that amount.

minReward number Specifies the minimum discount value a customer is guaranteed to receive when using a percentage-based discount coupon. If the calculated discount from the percentage is less than this value, the customer will still receive the minReward amount as a discount.

Example: Suppose a customer has a 10% discount coupon with a minReward of $5. If they make a purchase of $30, the 10% discount would ordinarily give them $3 off. However, since minReward is set to $5, the customer will receive the higher $5 discount instead. If they make a purchase of $60, the 10% discount would yield $6, which is above the minReward value, so they receive the full $6 discount.

minOrderValue number The minimum order value required for the coupon to be applied. Example: If the coupon requires a minimum purchase of $1,000 to apply, the minOrderValue will be 1000.

entitledProductIds array A list of product IDs that are eligible for the coupon. If provided, only these products can benefit from the coupon. Example: If the coupon is only valid for a specific product, the entitledProductIds array may contain IDs like ["productId123"] to indicate that only this product is eligible for the discount.

entitledVariantIds array A list of product variant IDs that are eligible for the coupon. If provided, only these product variants can benefit from the coupon. Example: If the coupon is valid for specific product variants, the entitledVariantIds array might include IDs like ["variantId456"], limiting the coupon to these variants.

entitledCollectionIds array A list of collection IDs that are eligible for the coupon. If provided, only these collections can benefit from the coupon. Example: If the coupon applies to an entire collection of products, the entitledCollectionIds array could include ["collectionId789"], indicating which collections the coupon can be used on.

entitledMerchantIdsarray

A list of merchant external IDs that are eligible to redeem the coupon. When provided, only the merchants with IDs in this list can benefit from or apply the coupon. This allows the coupon to be restricted to specific merchants, ensuring that it is valid only for certain merchants. If the array is empty or not provided, the coupon will be available to all merchants.

combinesWith.orderDiscounts boolean Indicates if the coupon can be combined with order-level discounts. Example: If the coupon cannot be combined with order discounts, this field will be set to false, ensuring that the coupon and other discounts will not apply together.

combinesWith.productDiscounts boolean Indicates if the coupon can be combined with product-specific discounts. Example: If the coupon cannot be used with existing product discounts, combinesWith.productDiscounts will be false, preventing customers from stacking discounts.

combinesWith.shippingDiscounts boolean Indicates if the coupon can be combined with shipping discounts. Example: If the coupon cannot be combined with free shipping offers, combinesWith.shippingDiscounts will be false.

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

{
  "valid": true,
  "coupon": {
    "code": "7wagbk72a4",
    "type": "shipping",
    "value": 100,
    "usageLimit": 1,
    "limitPerCustomer": 1,
    "startDate": "2024-10-17T08:22:00.0000Z",
    "expiryDate": "2027-10-17T08:22:00.0000Z",
    "capping": 400.0,
    "minReward": 123.0,
    "minOrderValue": 1000,
    "entitledProductIds": ["productId"],
    "entitledVariantIds": ["variantId"],
    "entitledCollectionIds": ["collectionId"],
    "combinesWith": {
      "orderDiscounts": false,
      "productDiscounts": false,
      "shippingDiscounts": false
    }
  },
  "lockReference": "22724237f5a44bd987e7bc63cbd06a0f",
  "dateToExpire": "2024-10-20T16:05:47.7699083Z"
}

POST - Validate Multiple Coupons

https://api.stg.gameball.co/api/v4/integrations/coupons/validate

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

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.

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 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.

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.

Sample request

{
  "customerId": "h5jxz",
  "mobile": "+1234567890",
  "email": "alex.jones@example.com",
  "coupons": [
    "5lvbtyhzpe",
    "8vj43ywdmc"
  ],
  "lock": true,
  "lockReference": null
}

Response

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.

Coupon Object

code string The generated coupon code that the customer will use. Example: If a coupon code like "7wagbk72a4" is generated for a customer, it can be used during checkout to apply the relevant discount or offer.

type string Type of the coupon, such as fixed amount, percentage discount, free shipping, or product-specific coupon.Possible Values :

  • shipping

  • fixed

  • percentage

  • product

value number The monetary value or percentage value of the coupon, depending on its type. Example: If a coupon provides a $100 discount, the value will be 100.

usageLimit number The total number of times the coupon can be used across all customers. Example: If a coupon can only be used once, the usageLimit will be set to 1, indicating that it cannot be reused after the first use.

limitPerCustomer number The number of times a single customer can use the coupon. Example: If each customer can only use the coupon one time, the limitPerCustomer will be set to 1, ensuring the coupon can only be redeemed once per customer.

startDate string The date and time when the coupon becomes valid and can be used. Example: If the coupon becomes valid on October 17, 2024, the startDate will be "2024-10-17T08:22:00.0000Z".

expiryDate string The date and time when the coupon will expire and no longer be valid. Example: If the coupon expires on October 17, 2027, the expiryDate will be "2027-10-17T08:22:00.0000Z".

capping number The maximum discount or value cap that the coupon can offer, even if the discount calculation exceeds this value. Example: If the maximum discount for the coupon is capped at $400, the capping will be set to 400, meaning the discount will not exceed that amount.

minReward number Specifies the minimum discount value a customer is guaranteed to receive when using a percentage-based discount coupon. If the calculated discount from the percentage is less than this value, the customer will still receive the minReward amount as a discount.

Example: Suppose a customer has a 10% discount coupon with a minReward of $5. If they make a purchase of $30, the 10% discount would ordinarily give them $3 off. However, since minReward is set to $5, the customer will receive the higher $5 discount instead. If they make a purchase of $60, the 10% discount would yield $6, which is above the minReward value, so they receive the full $6 discount.

minOrderValue number The minimum order value required for the coupon to be applied. Example: If the coupon requires a minimum purchase of $1,000 to apply, the minOrderValue will be 1000.

entitledProductIds array A list of product IDs that are eligible for the coupon. If provided, only these products can benefit from the coupon. Example: If the coupon is only valid for a specific product, the entitledProductIds array may contain IDs like ["productId123"] to indicate that only this product is eligible for the discount.

entitledVariantIds array A list of product variant IDs that are eligible for the coupon. If provided, only these product variants can benefit from the coupon. Example: If the coupon is valid for specific product variants, the entitledVariantIds array might include IDs like ["variantId456"], limiting the coupon to these variants.

entitledCollectionIds array A list of collection IDs that are eligible for the coupon. If provided, only these collections can benefit from the coupon. Example: If the coupon applies to an entire collection of products, the entitledCollectionIds array could include ["collectionId789"], indicating which collections the coupon can be used on.

entitledMerchantIdsarray

A list of merchant external IDs that are eligible to redeem the coupon. When provided, only the merchants with IDs in this list can benefit from or apply the coupon. This allows the coupon to be restricted to specific merchants, ensuring that it is valid only for certain merchants. If the array is empty or not provided, the coupon will be available to all merchants.

combinesWith.orderDiscounts boolean Indicates if the coupon can be combined with order-level discounts. Example: If the coupon cannot be combined with order discounts, this field will be set to false, ensuring that the coupon and other discounts will not apply together.

combinesWith.productDiscounts boolean Indicates if the coupon can be combined with product-specific discounts. Example: If the coupon cannot be used with existing product discounts, combinesWith.productDiscounts will be false, preventing customers from stacking discounts.

combinesWith.shippingDiscounts boolean Indicates if the coupon can be combined with shipping discounts. Example: If the coupon cannot be combined with free shipping offers, combinesWith.shippingDiscounts will be false.

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 Order API 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".

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

{
  "valid": true,
  "coupons": [
    {
      "code": "8vj43ywdmc",
      "type": "percentage",
      "value": 10,
      "usageLimit": 100,
      "limitPerCustomer": 1,
      "startDate": "2024-10-20T14:16:00Z",
      "expiryDate": "2025-01-20T15:14:00Z",
      "capping": 400,
      "minOrderValue": 1000,
      "entitledProductIds": ["productId"],
      "entitledVariantIds": ["variantId"],
      "entitledCollectionIds": ["collectionId"],
      "combinesWith": {
        "orderDiscounts": true,
        "productDiscounts": false,
        "shippingDiscounts": false
      }
    },
    {
      "code": "5lvbtyhzpe",
      "type": "percentage",
      "value": 15,
      "usageLimit": 200,
      "limitPerCustomer": 5,
      "startDate": "2024-10-20T14:22:00Z",
      "expiryDate": "2025-06-29T14:16:00Z",
      "capping": 250,
      "minOrderValue": 9999,
      "entitledProductIds": ["productId"],
      "entitledVariantIds": ["variantId"],
      "entitledCollectionIds": ["collectionId"],
      "combinesWith": {
        "orderDiscounts": true,
        "productDiscounts": false,
        "shippingDiscounts": false
      }
    }
  ],
  "lockReference": "74e20fc6bf7a4970ad3c125b1713194f",
  "dateToExpire": "2024-10-20T16:22:00.8249283Z"
}

POST - Burn Coupon 

https://api.gameball.co/api/v4/integrations/coupons/burn

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.

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.

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 coupons or lockReference 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 or lockReference must be provided for the request to proceed.

Sample request

{
    "customerId": "h5jxz",
    "email": "alex.jones@example.com",
    "mobile": "+1234567890",
    "coupons": [
        "COUPON123",
        "COUPON456"
    ],
    "lockReference": null
}

DELETE - Release Coupons

https://api.gameball.co/api/v4/integrations/Coupons/{lockReference}

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.

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.

PreviousTransaction ValidationNextConfigurations

Last updated