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

# Close Spend Accounts

# Overview

Each cash balance account can be closed, with all it's balance transferred and depending virtual cards' funding source changed or them being locked.

# Close User Cash Balance Account

## Sample request

You can close a user cash balance account with the `closeUserCashBalance` mutation. This mutation allows you to do the following:

* Close your spending account.
* Change virtual cards funding source if there are any that have this spending account as one.
* Lock related virtual cards.
* Transfer the remaining balance to another spend account.

The query takes a `CloseUserCashBalanceInput` input object.

```graphql theme={null}
mutation closeUserCashBalance($input: CloseUserCashBalanceInput!) {
    closeUserCashBalance(input: $input) {
        closedUserCashBalance {
            userCashBalanceId
            lifetimeCashBalance
            nickname
            status
            createdAt
            closedAt
        }
        affectedVirtualCards {
            virtualCardId
            virtualCardLast4
        }
    }
}
```

This mutation requires the `CloseUserCashBalanceInput` input type. Any field marked with an exclamation mark (`!`) in the schema is mandatory and must be included in the request.

## CloseUserCashBalanceInput

| Field name                | Type                              | Description                                                                                                                                                                 |
| :------------------------ | :-------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| idempotencyKey            | UUID!                             | A unique client-generated UUID to ensure a request is processed only once.                                                                                                  |
| userCashBalanceId         | UUID!                             | An unique identifier for the cash balance account.                                                                                                                          |
| newFundingSource          | CloseUserCashBalanceFundingSource | A new funding source for all dependent virtual cards. Required only if there are virtual cards tied to this cash balance account and `lockAllVirtualCards` is not provided. |
| lockAllVirtualCards       | Boolean                           | Whether to lock all dependent virtual cards. Required only if there are virtual cards tied to this cash balance account and `newFundingSource` is not provided.             |
| transferUserCashBalanceId | UUID                              | An unique identifier for the transfer. Required only if cash balance account's available balance is >0.                                                                     |

### Example

```json theme={null}
{
  "idempotencyKey": "65666780-c552-47f0-ba05-f90fced0ef9f",
  "userCashBalanceId": "ca8e1ccf-b42d-41d3-8cad-2237e020d1b1",
  "lockAllVirtualCards": true,
  "transferUserCashBalanceId": "6d1b4b19-deef-42f5-80d7-ec34804ce091"
}
```

## CloseUserCashBalanceFundingSource

| Field name                                                   | Type                     | Description                                                                                  |
| :----------------------------------------------------------- | :----------------------- | :------------------------------------------------------------------------------------------- |
| bankAccountId                                                | UUID                     | An unique identifier for the bank account. Required if other options aren't present.         |
| userCashBalanceId                                            | UUID                     | An unique identifier for the cash balance account. Required if other options aren't present. |
| primaryFundingSource:                                        | VirtualCardFundingSource | A type of a primary funding source, either `FLUZ_BALANCE`                                    |
| or `BANK_ACCOUNT`. Required if other options aren't present. |                          |                                                                                              |

### Example

```json theme={null}
{
  "userCashBalanceId": "ca8e1ccf-b42d-41d3-8cad-2237e020d1b1",
}
```

## Sample response

The response from the `closeUserCashBalance` mutation will include a closed cash balance account details, including its unique identifier and a list of affected virtual cards.

```json theme={null}
{
    "data": {
        "closeUserCashBalance": {
            "closedUserCashBalance": {
                "userCashBalanceId": "ca8e1ccf-b42d-41d3-8cad-2237e020d1b1",
                "lifetimeCashBalance": "0.00000",
                "nickname": "Closed Spend Account",
                "status": "CLOSED",
                "createdAt": "2025-12-30T21:18:26.782Z",
                "closedAt": "2025-12-30T21:22:29.359Z"
            },
            "affectedVirtualCards": [
                {
                    "virtualCardId": "afad4d6d-11f0-4ac1-b971-caca7c34c77c",
                    "virtualCardLast4": "4473"
                }
            ]
        }
    }
}
```

### Response Fields

| Field name           | Type                                       | Description                                      |
| :------------------- | :----------------------------------------- | :----------------------------------------------- |
| closeUserCashBalance | ClosedUserCashBalance!                     | Closed cash balance account details.             |
| lifetimeCashBalance  | \[CloseUserCashBalanceResponseVirtualCard] | A list of virtual cards affected by the closure. |

#### closeUserCashBalance

| Field name          | Type                   | Description                                                 |
| :------------------ | :--------------------- | :---------------------------------------------------------- |
| userCashBalanceId   | UUID!                  | Unique identifier for the cash balance account.             |
| 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 (should be `CLOSED`).         |
| createdAt           | DateTime!              | Timestamp when the account was created.                     |
| closedAt            | DateTime!              | Timestamp when the account was closed.                      |

#### affectedVirtualCards

| Field name       | Type  | Description                                      |
| :--------------- | :---- | :----------------------------------------------- |
| virtualCardId    | UUID! | Unique identifier for the virtual card.          |
| virtualCardLast4 | UUID! | The last four digits of the virtual card number. |

<br />

> ❗️ Authorization required
>
> This mutation requires the `MANAGE_PAYMENT` scope. Ensure your access token has been granted this scope before attempting to create a cash balance account.