Skip to main content
GET
/
api
/
v4.0
/
integrations
/
customers
/
{customerId}
/
balance
Get Customer Balance
curl --request GET \
  --url https://api.gameball.co/api/v4.0/integrations/customers/{customerId}/balance \
  --header 'apikey: <api-key>'
{
  "totalPointsBalance": 1500,
  "totalPointsValue": 75,
  "availablePointsBalance": 1200,
  "availablePointsValue": 60,
  "pendingPoints": 300,
  "pendingPointsValue": 15,
  "currency": "USD",
  "pointsName": "Reward Points",
  "nextExpiringPointsAmount": 200,
  "nextExpiringPointsValue": 10,
  "nextExpiringPointsDate": "2024-12-01T00:00:00",
  "totalEarnedPoints": 2500
}
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 apikey and secretkey headers.

Authorizations

​
apikey
string
header
required

Path Parameters

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

Query Parameters

​
expand
string

Comma-separated expansions: tier,referrals

Response

200 - application/json

Customer balance retrieved successfully

​
totalPointsBalance
number

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

​
totalPointsValue
number

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

​
availablePointsBalance
number

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

​
availablePointsValue
number

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

​
pendingPoints
number

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.

​
pendingPointsValue
number

The monetary value of the pending points.

​
currency
string

The currency in which the points value is calculated.

​
pointsName
string

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

​
nextExpiringPointsAmount
number

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.

​
nextExpiringPointsValue
number

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.

​
nextExpiringPointsDate
string

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.

​
totalEarnedPoints
number

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.