> This page is for Cash App Pay Partner API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.cash.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.cash.app/_mcp/server.

### Schema (`response.body`)

```yaml
openapi: 3.1.0
info:
  title: API
  version: 1.0.0
paths:
  /balances/{balance_id}:
    get:
      operationId: subpackageBalances_retrieve-balance
      summary: Retrieve balance
      description: >-
        <Warning title="Beta" icon="robot-astromech">

        Balances is a **beta** feature. We're actively improving this API based
        on your feedback.

        </Warning>


        Retrieves a balance by its ID.


        Scopes: `BALANCES_READ`
      tags:
        - subpackage_balances
      parameters:
        - name: balance_id
          in: path
          description: The ID of the balance to retrieve.
          required: true
          schema:
            type: string
        - name: grant_id
          in: query
          description: >-
            ID of the grant that authorizes reading the customer's balances.
            This grant is created when a customer approves a `CHECKING_BALANCE`
            action in the Customer Request API.
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 256
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/balances_RetrieveBalanceResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveBalanceRequestNotFoundErrorBody'
tags:
  - name: subpackage_balances
servers:
  - url: https://api.cash.app/network/v1
    description: Production
  - url: https://sandbox.api.cash.app/network/v1
    description: Sandbox
components:
  schemas:
    balances_BalanceType:
      type: string
      enum:
        - CHECKING
      description: The type of balance.
      title: BalanceType
    Currency:
      type: string
      enum:
        - USD
      description: >-
        Indicates the country associated with an entity. Values are from the
        [ISO-4217 Alpha-3](https://www.iso.org/iso-4217-currency-codes.html)
        specification.


        Current values:


        - `USD`: United States Dollar
      title: Currency
    balances_Balance:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 256
          description: |-
            Unique identifier for this balance issued by Cash App.

            Min length: `1`
            Max length: `256`
        customer_id:
          type: string
          minLength: 1
          maxLength: 128
          description: |-
            ID of the customer associated with this balance.

            Min length: `1`
            Max length: `128`
        type:
          $ref: '#/components/schemas/balances_BalanceType'
        currency:
          $ref: '#/components/schemas/Currency'
        amount:
          type: integer
          description: >-
            The balance amount, in the lowest denomination of the currency (for
            example, cents for USD).
        created_at:
          type: string
          format: date-time
          description: >-
            When this balance was created, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
        updated_at:
          type: string
          format: date-time
          description: >-
            When this balance was last updated, in [RFC
            3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC).
      required:
        - id
        - customer_id
        - type
        - currency
        - amount
      title: Balance
    balances_RetrieveBalanceResponse:
      type: object
      properties:
        balance:
          $ref: '#/components/schemas/balances_Balance'
      required:
        - balance
      title: RetrieveBalanceResponse
    ErrorCategory:
      type: string
      enum:
        - API_ERROR
        - AUTHENTICATION_ERROR
        - BRAND_ERROR
        - DISPUTE_ERROR
        - MERCHANT_ERROR
        - INVALID_REQUEST_ERROR
        - PAYMENT_PROCESSING_ERROR
        - RATE_LIMIT_ERROR
        - WEBHOOK_ERROR
        - API_KEY_ERROR
        - GRANT_ERROR
      description: The high-level reason the error occurred.
      title: ErrorCategory
    Error:
      type: object
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: The high-level reason the error occurred.
        code:
          type: string
          description: >-
            A unique identifier for the specific type of error that occurred.
            For more information, see [Error Code
            Reference](/cash-app-pay-partner-api/guides/technical-guides/api-fundamentals/errors/error-code-reference).


            Min length: `1`
        detail:
          type: string
          description: >-
            Human-readable description of why the error occurred and how to
            resolve it.


            Min length: `1`
        field:
          type: string
          description: >-
            The field in the request that caused the error, using array and
            object dot notation.


            Min length: `1`
      required:
        - category
        - code
      description: Represents an error encountered during a request to the API.
      title: Error
    RetrieveBalanceRequestNotFoundErrorBody:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      required:
        - errors
      title: RetrieveBalanceRequestNotFoundErrorBody

```

**`Example`**

```json Example
{
  "id": "BAL_1a5ba026f4c8977d63f0cbdcfe62a13dc077b2f4ab6624b19c4dfd8f4eb26644a12c5b78d0e34d19e460da2af7f31e08",
  "customer_id": "CST_AQmxh4y_QGoNNIG5NUw0jttqyYedL1LklACQdyJ3H-Vs6WmLtP6A_C7XjQNohvY",
  "type": "CHECKING",
  "currency": "USD",
  "amount": 1500,
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}
```