Skip to main content

​
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.
AttributeDescriptionUsage Recommendation
isExpiredtrue if the promotion’s expiry date has passed.Exclude expired promotions from the main display or show them under an “Expired” section.
isActivetrue if the promotion is currently active in Gameball.Display only active promotions.
usageLimitMaximum number of times this promotion can be used globally.Compare with usedCount to check remaining availability.
limitPerCustomerNumber of times each customer can redeem the promotion.Compare with customerUsedCount to decide eligibility.
usedCountTotal number of times this promotion has been redeemed globally.Useful for analytics or visibility into overall usage.
customerUsedCountNumber of times this specific customer has redeemed the promotion.Use to determine if the customer can use it again.
isAvailableToUsetrue 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

ChannelExample Use
🛍️ E-commerceDisplay ongoing promotions during checkout or in the user dashboard.
📱 Mobile AppPopulate 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.
1

Fetch promotions

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

Filter the response

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

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