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

PreviousTransaction Validation NextConfigurations

Last updated 16 days ago

Coupons

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 .

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.

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

Request

Path Parameters

code string Required The coupon code you want to validate.

Body

application/json

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.

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.

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

Request

Body

application/json

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.

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.

lockDurationinteger Optional

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.

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

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

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.

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.

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.

entitledMerchantIdsarray

Example: If a coupon is locked for a transaction, the lockReference could be something like "74e20fc6bf7a4970ad3c125b1713194f".

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.

Request

Body

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
}

GET - Lock Details

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

This API gets the details of the provided {lockReference} in Gameball.

Security: Requires apikey and secretkey headers

Request

Path Parameters

lockReference string Required The lock reference identifer to get it's details.

Response

application/json

customerId string

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.

isUsed boolean

Indicates whether the provided lock is marked as used or not by the customer.

usedAt string optional

The date and time when the provided lock was marked as used.

isExpired boolean

Indicates whether the provided lock is marked as expired or or not.

expiredAt string optional

The date and time when the provided lock was marked as expired.

coupons array The coupon details that are assoicated with the provided lock reference.

Coupon Object

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.

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.

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.

entitledMerchantIdsarray

Sample Response

{
    "customerId": "cust_123456789",
    "lockReference": "74e20fc6bf7a4970ad3c125b1713194f",
    "isUsed": false,
    "isExpired": true,
    "expiredAt": "2024-10-20T16:22:00.8249283Z",
    "usedAt": null,
    "coupons": [
        {
            "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
            }
        }
    ]
}

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.

POST - Automatic Coupons

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

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.

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.

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.

lineItems object

productId string Optional Unique identifier for the product or service being purchased.

quantity float Optional Number of units purchased for this product or service.

price float Optional The original price of a single product before any tax or discount is applied. This reflects the cost of one unit of the item, not the total for multiple quantities in an order.

Example: If the original price of a product is $50 and a customer buys two units, the price for each item would still be recorded as $50, regardless of quantity.

sku string Optional Stock Keeping Unit (SKU) for the product.

tags array Optional Tags associated with the product for categorization or promotional purposes.

category array Optional Product category, such as fashion or electronics. It can include one or multiple categories. Example: ["natural", "cosmetics"]

weight float Optional Weight of the product.

vendor string Optional Vendor or manufacturer of the product.

collection array Optional Collection ID(s) to which the product belongs. It can include one or multiple collections. Example: ["14313", "4343"]

title string Optional Product title or name.

taxes float Optional The total amount of taxes applied to the line item, expressed in the shop's currency. This amount must be positive and reflects the total taxes based on the quantity of the item.

discount float Optional The total discount applied to this line item, expressed as a positive value. This amount should reflect the total discounts based on the quantity of the item.

extra object Optional Key-value pairs containing any extra information about the product, such as size, color, or other custom attributes. The values must be of type string or number.

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.

merchant object

uniqueId string Optional Unique identifier for the merchant.

name string Optional Name of the merchant.

branch.uniqueId string Required Unique identifier for the branch where the order took place.

branch.name string Optional Name of the branch where the order took place.

Sample Request

{
  "customerId": "cust_123456789",
  "totalPrice": 300,
  "lineItems": [
    {
      "price": 100,
      "quantity": 3,
      "productId": "PROD98765",
      "sku": "SKU98765",
      "tags": [
        "electronics",
        "smartphone"
      ],
      "category": [
        "mobile phones"
      ],
      "weight": 0.5,
      "vendor": "TechVendor",
      "collection": [
        "latest gadgets"
      ],
      "title": "Smartphone XYZ",
      "taxes": 7.5,
      "discount": 25,
      "extra": {
        "subClass": "SUBCLASS123"
      }
    }
  ],
  "merchant": {
    "uniqueId": "MERCH001",
    "name": "TechGadgetStore",
    "branch": {
      "uniqueId": "BRANCH001",
      "name": "Downtown Branch"
    }
  },
  "cartId": "CART98765"
}

Response

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.

discountedItem object

productId string Unique identifier for the product or service.

quantity number Number of units purchased for this product or service.

discount float The total discount applied to this line item.

price float The original price of a single product.

Sample Response

{
  "isApplied": true,
  "couponName": "Buy 2 Get 1",
  "discountAmount": 50,
  "discountType": "buyX_getY",
  "discountedItems": [
    {
      "price": 100,
      "quantity": 1,
      "productId": "PROD98765",
      "sku": "SKU98765",
      "tags": [
        "electronics",
        "smartphone"
      ],
      "category": [
        "mobile phones"
      ],
      "weight": 0.5,
      "vendor": "TechVendor",
      "collection": [
        "latest gadgets"
      ],
      "title": "Smartphone XYZ",
      "taxes": 7.5,
      "discount": 50,
      "extra": {
        "subClass": "SUBCLASS123"
      }
    }
  ]
}

PreviousTransaction Validation NextConfigurations

Last updated 16 days ago