> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Balance

> Retrieve a customer's current points balance including redeemable points and their monetary equivalent.

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.

<Info>
  **Security**: Requires **apikey** and **secretkey** headers.
</Info>


## OpenAPI

````yaml GET /api/v4.0/integrations/customers/{customerId}/balance
openapi: 3.1.0
info:
  title: Gameball API
  description: >-
    Gameball REST API v4.0 - Complete API reference for integrating loyalty,
    gamification, and customer engagement features
  version: 4.0.0
servers:
  - url: https://api.gameball.co
security:
  - bearerAuth: []
paths:
  /api/v4.0/integrations/customers/{customerId}/balance:
    get:
      summary: Get Customer Balance
      description: >-
        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.
      operationId: getCustomerBalance
      parameters:
        - name: customerId
          in: path
          required: true
          description: >-
            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.
          schema:
            type: string
        - name: expand
          in: query
          required: false
          schema:
            type: string
          description: 'Comma-separated expansions: tier,referrals'
      responses:
        '200':
          description: Customer balance retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerBalanceResponse'
              example:
                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
      security:
        - apiKey: []
          secretKey: []
components:
  schemas:
    CustomerBalanceResponse:
      type: object
      properties:
        totalPointsBalance:
          type: number
          description: >-
            The total number of points the customer has, including pending
            points.
        totalPointsValue:
          type: number
          description: >-
            The total monetary value of the customer's points, including pending
            points.
        availablePointsBalance:
          type: number
          description: >-
            The number of points that are currently active and available for use
            (excludes pending points).
        availablePointsValue:
          type: number
          description: >-
            The monetary value of the points that are currently active and
            available for use (excludes pending points).
        pendingPoints:
          type: number
          description: >-
            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:
          type: number
          description: The monetary value of the pending points.
        currency:
          type: string
          description: The currency in which the points value is calculated.
        pointsName:
          type: string
          description: >-
            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:
          type: number
          description: >-
            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:
          type: number
          description: >-
            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:
          type: string
          description: >-
            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:
          type: number
          description: >-
            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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKey:
      type: apiKey
      in: header
      name: apikey
    secretKey:
      type: apiKey
      in: header
      name: secretkey

````