Sign in

v36

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-017439390.7 KB

Get Customer Balance

This API retrieves a customer's current points balance within Gameball, including redeemable points and their monetary equivalent. It provides detailed balance information, such as total, available, and pending points, along with upcoming expirations.

Security: Requires both apikey and secretkey headers.

get/api/v4.0/integrations/customers/{customerId}/balance

Path parameters

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

Query parameters

expandstring

Comma-separated expansions: tier,referrals

Response

Customer balance retrieved successfully

totalPointsBalancenumber

The total number of points the customer has, including pending points.

totalPointsValuenumber

The total monetary value of the customer's points, including pending points.

availablePointsBalancenumber

The number of points that are currently active and available for use (excludes pending points).

availablePointsValuenumber

The monetary value of the points that are currently active and available for use (excludes pending points).

pendingPointsnumber

The points earned by the customer that are temporarily on hold during the return window configured for your account. These points will remain in a pending status until the return period expires, ensuring that the points are not used or redeemed until it is confirmed that the transaction is final and not subject to returns or cancellations. Example: If a customer places an order and earns 100 points, and your account is configured with a 14-day return window, these 100 points will remain pending for 14 days. During this time, the customer cannot use or redeem the points. After the 14-day window expires and the order is confirmed as final, the 100 points will become available for the customer to use.

pendingPointsValuenumber

The monetary value of the pending points.

currencystring

The currency in which the points value is calculated.

pointsNamestring

The name of the points used in your loyalty program that appears to customers. This is the term your customers will see when they earn or redeem points. Example: If your loyalty program rewards customers with "Stars" instead of generic "Points", the value of pointsName could be "Stars".

nextExpiringPointsAmountnumber

The amount of points that are set to expire next. Points expire when the configured point expiry duration has passed, and the points have not been used within that time frame.

nextExpiringPointsValuenumber

The monetary value of the points that are set to expire next. Points expire when the configured point expiry duration has passed, and the points have not been used within that time frame.

nextExpiringPointsDatestring

The date when the next set of points will expire. Points expire when the configured point expiry duration has passed, and the points have not been used within that time frame.

totalEarnedPointsnumber

The total number of points that the customer has earned over their entire lifetime within the Gameball program. This includes all points accumulated from various activities like cashback rewards, referrals, or rewards campaigns.