Get Customer Coupons API

Retrieving a customer’s active coupons allows your application to show users what promotions or discounts they can apply during checkout.
This API helps you display live coupon data directly within your storefront, mobile app, or POS system, ensuring customers can use their benefits conveniently.

Overview

The Get Customer Coupons API returns all active and eligible coupons linked to a specific customer.
Each coupon includes details such as:

🟢 Coupon status (active, expired, or used)
💸 Discount type and value
📅 Expiration date
🔢 Usage limits and remaining uses

This data can be used to build custom checkout experiences, rewards dashboards, or loyalty widgets.

When to Use It

Channel	Example Use
🛍️ E-commerce	Display the customer’s available coupons on the checkout or profile page.
📱 Mobile App	Show “My Coupons” in a loyalty or rewards tab.
🏪 POS (Retail)	Allow cashiers to view and apply valid coupons when identifying a customer.

Important: Filtering Is Done on Your End

Gameball’s API returns all coupons, not only the active or valid ones.
To determine which coupons to display to customers, use the attributes returned in each coupon object. Image(137) Pn

Attribute	Description	Usage Recommendation
`isExpired`	`true` if the coupon’s expiry date has passed.	Hide expired coupons from the UI or show them under an “Expired” section.
`isActive`	`true` if the coupon is currently active and not deactivated by the admin.	Show only active coupons to users.
`usageLimit`	The total number of times this coupon can be used globally (across all customers).	Track whether the coupon has reached its max usage.
`limitPerCustomer`	The maximum number of times this coupon can be used by a single customer.	Use to determine if the customer has remaining uses.
`usedCount`	How many times has this coupon been used globally.	Compare with `usageLimit` to see if it’s still available.
`customerUsedCount`	How many times has this specific customer used this coupon.	Compare with `limitPerCustomer` to check individual eligibility.
`isAvailableToUse`	`true` if the coupon is both active and available for this customer to use.	Ideal flag to directly determine if the coupon should appear as “Usable.”

You can use You can use isAvailableToUse as the primary flag to display only coupons that are both active and usable. However, for more control, combine it withisExpired,limitPerCustomer, andcustomerUsedCount for custom logic.

Example Scenarios

Scenario 1: Displaying Active Coupons at Checkout

When a customer is logged in, you can fetch and display their valid coupons dynamically before they pay.

Fetch coupons

Call the Get Customer Coupons API using the customer’s customerId

Display them in the UI

List all returned coupons so the customer can select one to apply at checkout.

Apply on selection

When the customer selects a coupon, pass its code to the Validate API before calling the Order API/Burn API.

To understand how to burn coupons, refer to this tutorial

Example Request

GET /integrations/customers/{customerId}/coupons

Example Response

{
  "coupons": [
    {
      "code": "SPRING10",
      "type": "percentage_discount",
      "value": 10,
      "expiryDate": "2025-06-30T23:59:59Z",
      "usedCount": 1,
      "usageLimit": 3,
      "status": "Active"
    },
    {
      "code": "FREESHIP",
      "type": "free_shipping",
      "expiryDate": "2025-12-31T23:59:59Z",
      "usedCount": 0,
      "usageLimit": 1,
      "status": "Active"
    }
  ]
}

You can display coupon metadata (like type or value) in your checkout UI for transparency.
Example: “SPRING10 – Get 10% off until June 30.”

Filtering Logic Example

Here’s a simple way to determine which coupons to show to customers in your frontend or app:

const validCoupons = coupons.filter(
  (coupon) =>
    coupon.isActive &&
    !coupon.isExpired &&
    coupon.isAvailableToUse &&
    coupon.customerUsedCount < coupon.limitPerCustomer
);

This ensures your customer only sees coupons that are:

Active

Not Expired

Not already used to their limit

Available for redemption

You can still display expired or used coupons in a separate “History” or “Expired Coupons” section for transparency.

If you’re using the built-in Gameball Widget, you don’t need to integrate this API directly; the My Coupons section automatically fetches and displays all active coupons for the logged-in customer.

This API is mainly required when you are building a custom UI for displaying loyalty coupons instead of using the built-in widget.

Key Notes for Developers

Always use the latest customerId when retrieving coupons, especially for merged profiles (email + mobile).

Coupons can be validated or locked through the Validate Coupon API before checkout.

Use the Burn or Release APIs after purchase completion or payment failure to finalize the coupon lifecycle.

Key Takeaways