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

# Get Spend Accounts

After creating a spend account, you can access it through the following queries:

1. `getUserCashBalances` - retrieves a list of all your spend accounts.
2. `getUserCashBalanceById` - retrieves a specific spend account based on it's id value.

<Warning>
  **Authorization required**

  This mutation requires the `LIST_PAYMENT` scope. Ensure your access token has been granted this scope before attempting to transfer funds internally.
</Warning>

## Spend Account details

The `UserCashBalanceDetails` object will contain important information about the spend account.

| Field name           | Type                   | Description                                                |
| :------------------- | :--------------------- | :--------------------------------------------------------- |
| userCashBalanceId    | UUID!                  | Unique identifier for the cash balance account             |
| totalCashBalance     | String!                | Total cash balance in the account (starts at 0)            |
| availableCashBalance | String!                | Available cash balance for immediate use (starts at 0)     |
| lifetimeCashBalance  | String!                | Cumulative total of all funds ever deposited (starts at 0) |
| nickname             | String                 | The custom name assigned to the account                    |
| status               | UserCashBalanceStatus! | Current status of the account (ACTIVE, CLOSED)             |
| isDefault            | Boolean!               | Whether spend account is the default one                   |
| createdAt            | DateTime!              | Timestamp when the account was created                     |
| updatedAt            | DateTime!              | Timestamp when the account was updated                     |

## Retrieve the Spend Account List

To obtain a list of spend accounts created on your account, use the `getUserCashBalances` query. This call returns a list of spend accounts with basic details, including the `userCashBalanceId`. You will need this ID to retrieve a specific spend account through `getuserCashBalanceById`.

### Variables

| Field    | Type                       | Required | Description                                         |
| -------- | -------------------------- | -------- | --------------------------------------------------- |
| filter   | UserCashBalanceFilterInput | No       | Filtering criteria for spend accounts               |
| paginate | OffsetInput                | No       | Pagination parameters (default: limit=20, offset=0) |

### Sample Request

```graphql theme={null}
query GetUserCashBalances(
  $filter: UserCashBalanceFilterInput,
  $paginate: OffsetInput,
) {
  getUserCashBalances(
    filter: $filter
    paginate: $paginate
  ) {
    userCashBalances {
        userCashBalanceId
        totalCashBalance
        availableCashBalance
        lifetimeCashBalance
        nickname
        status
        isDefault
        createdAt
        updatedAt
    }
    totalCount
    hasNextPage
  }
}
```

<Note>
  Please note that due to rate-limiting, you might need to paginate and call the spend account list a few times.
</Note>

### Sample Response

The response will contain a list of spend accounts

```json JSON theme={null}
{
    "data": {
        "getUserCashBalances": {
            "userCashBalances": [
                {
                    "userCashBalanceId": "c115604e-5d47-473c-a955-41a820cdcaf8",
                    "totalCashBalance": "0.00",
                    "availableCashBalance": "0.00",
                    "lifetimeCashBalance": "768.00",
                    "nickname": "Virtual Prepaid Account",
                    "status": "ACTIVE",
                    "isDefault": false,
                    "createdAt": "2025-10-10T15:30:02.535Z",
                    "updatedAt": "2026-04-22T16:07:18.618Z"
                },
                {
                    "userCashBalanceId": "1c1b5fcc-eb21-44c5-b678-9c41f3fa21b4",
                    "totalCashBalance": "36.00",
                    "availableCashBalance": "36.00",
                    "lifetimeCashBalance": "177.00",
                    "nickname": "austin1",
                    "status": "ACTIVE",
                    "isDefault": false,
                    "createdAt": "2026-02-27T22:18:28.814Z",
                    "updatedAt": "2026-04-22T15:43:52.031Z"
                },
                {
                    "userCashBalanceId": "6d1b4b19-deef-42f5-80d7-ec34804ce090",
                    "totalCashBalance": "425108.80",
                    "availableCashBalance": "425108.80",
                    "lifetimeCashBalance": "444096.44",
                    "nickname": "Main account",
                    "status": "ACTIVE",
                    "isDefault": true,
                    "createdAt": "2025-08-01T19:25:54.392Z",
                    "updatedAt": "2026-04-21T19:19:22.777Z"
                }
            ],
            "totalCount": 3,
            "hasNextPage": false
        }
    }
}
```

### Filter Options

| Field             | Type                      | Description                                        |
| :---------------- | :------------------------ | :------------------------------------------------- |
| userCashBalanceId | \[UUID!]                  | Filter by specific spend account IDs               |
| nickname          | \[String!]                | Filter by spend accounts nicknames                 |
| status            | \[UserCashBalanceStatus!] | Filter by spend account status                     |
| isDefault         | Boolean                   | Filter by whether spend account is the default one |
| createdGte        | DateTime                  | Filter by creation date (greater than or equal)    |
| createdLte        | DateTime                  | Filter by creation date (less than or equal)       |
| updatedGte        | DateTime                  | Filter by update date (greater than or equal)      |
| updatedLte        | DateTime                  | Filter by update date (less than or equal)         |

**Example - Get only `ACTIVE` spend accounts**

```json theme={null}
{
	"filter": {
  	"status": [ACTIVE]
  }
}
```

### Pagination

| Field  | Type | Default | Max | Description                               |
| ------ | ---- | ------- | --- | ----------------------------------------- |
| limit  | Int  | 20      | 20  | Number of transactions to return per page |
| offset | Int  | 0       | -   | Number of transactions to skip            |

**Example - Page 1**:

```json theme={null}
{
	"paginate": {
  	"limit": 20,
  	"offset": 0
  }
}
```

**Example - Page 2**:

```json theme={null}
{
	"paginate": {
  	"limit": 20,
  	"offset": 20,
	}
}
```

## Retrieve a specific Spend Account

To obtain a specific spend account created on your account, use the `getUserCashBalanceById` query. This call returns this spend account's details, including the `userCashBalanceId` & it's balances.

### Variables

| Field             | Type    | Required | Description        |
| ----------------- | ------- | -------- | ------------------ |
| userCashBalanceId | String! | Yes      | Spend account's ID |

### Sample Request

```graphql theme={null}
query GetUserCashBalanceById(
  $userCashBalanceId: String
) {
  getUserCashBalanceById(
    userCashBalanceId: $userCashBalanceId
  ) {
    userCashBalanceId
    totalCashBalance
    availableCashBalance
    lifetimeCashBalance
    nickname
    status
    isDefault
    createdAt
    updatedAt
  }
}
```

### Sample Response

The response will contain a specific spend account's details

```json JSON theme={null}
{
    "data": {
        "getUserCashBalanceById": {
            "userCashBalanceId": "6d1b4b19-deef-42f5-80d7-ec34804ce090",
            "totalCashBalance": "425108.80",
            "availableCashBalance": "425108.80",
            "lifetimeCashBalance": "444096.44",
            "nickname": "Main account",
            "status": "ACTIVE",
            "isDefault": true,
            "createdAt": "2025-08-01T19:25:54.392Z",
            "updatedAt": "2026-04-21T19:19:22.777Z"
        }
    }
}
```

<br />