Retrieve Promotions

Retrieving a customer’s available promotions allows your platform to display active offers, personalized deals, or rewards-based discounts in real time.
This API lets you showcase ongoing promotions directly within your storefront, mobile app, or POS system, empowering customers to redeem their offers at checkout.

Overview

The Get Customer Coupons API returns all promotions assigned to a customer, including both active and expired ones. Each promotion includes details such as:

🏷️ Promotion name and type
💰 Discount value or benefit
📅 Expiry date and status
🎯 Eligibility and usage limits

This API is ideal for building personalized “My Promotions” sections or showing available promotions at checkout.

Important: Filtering Is Done on Your End

Gameball’s Promo Engine returns all promotions associated with the customer — whether they’re active, expired, or already used.
To show only the valid ones, you’ll need to filter them on your side using the attributes provided in the API response.

Attribute	Description	Usage Recommendation
`isExpired`	`true` if the promotion’s expiry date has passed.	Exclude expired promotions from the main display or show them under an “Expired” section.
`isActive`	`true` if the promotion is currently active in Gameball.	Display only active promotions.
`usageLimit`	Maximum number of times this promotion can be used globally.	Compare with `usedCount` to check remaining availability.
`limitPerCustomer`	Number of times each customer can redeem the promotion.	Compare with `customerUsedCount` to decide eligibility.
`usedCount`	Total number of times this promotion has been redeemed globally.	Useful for analytics or visibility into overall usage.
`customerUsedCount`	Number of times this specific customer has redeemed the promotion.	Use to determine if the customer can use it again.
`isAvailableToUse`	`true` if the promotion is currently valid and redeemable for this customer.	Main flag for determining usability in your UI.

Use <code>isAvailableToUse as the key flag to show active, valid promotions.For more precision, combine it with isExpired,customerUsedCount, and limitPerCustomer in your display logic.

When to Use It

Channel	Example Use
🛍️ E-commerce	Display ongoing promotions during checkout or in the user dashboard.
📱 Mobile App	Populate a “My Promotions” tab showing active and expired deals.
🏪 POS (Retail)	Let store clerks view applicable promotions for returning customers.

Example Scenario: Showing Promotions in Checkout

When a customer signs in, your system can fetch all available promotions from Gameball and display those that are currently active and usable.

Fetch promotions

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

Filter the response

Use the metadata flags (isExpired,isActive, isAvailableToUse) to filter out inactive or used promotions.

Display in the UI

Show filtered, valid promotions so customers can easily apply them at checkout.

Example Request

GET /integrations/customers/{customerId}/promotions

Example Response

{
  "coupons": [
    {
      "code": "WELCOME20",
      "name": "Welcome Offer",
      "type": "percentage_discount",
      "value": 20,
      "expiryDate": "2025-07-01T23:59:59Z",
      "isExpired": false,
      "isActive": true,
      "usageLimit": 500,
      "limitPerCustomer": 1,
      "usedCount": 120,
      "customerUsedCount": 0,
      "isAvailableToUse": true
    },
    {
      "code": "LOYALTYBOOST",
      "name": "Loyalty Booster",
      "type": "fixed_discount",
      "value": 15,
      "expiryDate": "2025-03-01T23:59:59Z",
      "isExpired": true,
      "isActive": true,
      "usageLimit": 100,
      "limitPerCustomer": 1,
      "usedCount": 100,
      "customerUsedCount": 1,
      "isAvailableToUse": false
    }
  ]
}

Filtering Logic Example

You can apply simple client-side filtering to show only the promotions available for redemption:

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

This ensures customers see promotions that are:

Optionally, group promotions by state, for example: Active, Used, and Expired, to create a cleaner user experience.

Key Takeaways

Get Customer Coupons API

Retrieve promotions linked to a customer profile

Automatic Promos Tutorial

Apply eligible promotions automatically at checkout

Burn Promo Tutorial

Finalize promotions after order success

Coupon Entity Reference

Review metadata shared between coupons and promos

Getting Started

General

Experiences

More

Display Promo Codes for Customers

Retrieve Promotions

Overview

Important: Filtering Is Done on Your End

When to Use It

Example Scenario: Showing Promotions in Checkout

Example Request

Example Response

Filtering Logic Example

Key Takeaways

Get Customer Coupons API

Automatic Promos Tutorial

Burn Promo Tutorial

Coupon Entity Reference

​Retrieve Promotions

​Overview

​Important: Filtering Is Done on Your End

​When to Use It

​Example Scenario: Showing Promotions in Checkout

​Example Request

​Example Response

​Filtering Logic Example

​Key Takeaways

​Related Resources

Get Customer Coupons API

Automatic Promos Tutorial

Burn Promo Tutorial

Coupon Entity Reference

Retrieve Promotions

Overview

Important: Filtering Is Done on Your End

When to Use It

Example Scenario: Showing Promotions in Checkout

Example Request

Example Response

Filtering Logic Example

Key Takeaways

Related Resources