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

# Managing Spend Power

Once a bank account is linked (see *Linking a Plaid Bank Account*), you can read its balance and spend power and, when you need a fresher reading, trigger a realtime balance refresh.

## What spend power means

**Spend power** is how much a user can currently spend from a linked bank account. It is based on the account's most recent known balance, reduced by recent ACH outflows that have not fully settled yet. When a user spends from the account, those amounts are held for roughly three business days before they clear and stop counting against spend power. (The exact clearing window is set per bank and can be shorter.)

Fluz keeps the stored balance for each linked account up to date automatically. When you need a more current reading — for example, right after a user moves money in or out of their bank — request a **realtime refresh** (rate limited; see below). Refreshing the balance updates the balance-derived spend-power figure.

## Auth

Call `/api/v1/graphql` with a Fluz user Bearer access token that includes `MANAGE_PAYMENT`. Basic auth is not allowed on these fields.

```http theme={null}
Authorization: Bearer <fluz-user-access-token>
```

## Get spend power for one bank account

```graphql theme={null}
query GetPlaidBankAccountSpendPower($input: PlaidBankAccountInput!) {
  getPlaidBankAccountSpendPower(input: $input) {
    bankAccountId
    spendPower
    availableSpendPower
    lastRecordedBalance
    pendingTransactions
    updatedAt
  }
}
```

```json theme={null}
{
  "input": {
    "bankAccountId": "bank-account-id"
  }
}
```

**Response fields**

| Field                 | Description                                                                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lastRecordedBalance` | The most recent known bank balance for the account.                                                                                                                |
| `pendingTransactions` | Recent ACH outflows (debits from roughly the last three business days) that have not yet settled and are still being held against the balance.                     |
| `availableSpendPower` | What the user can spend right now, derived from the latest balance less pending. Moves immediately after a realtime balance refresh.                               |
| `spendPower`          | The account's decisioned spend-power figure. May update on a slower cadence than the balance, so it can briefly differ from `availableSpendPower` after a refresh. |
| `updatedAt`           | When the figure was last computed.                                                                                                                                 |

## Get the latest stored balance

For one bank account:

```graphql theme={null}
query GetPlaidBankAccountBalance($input: PlaidBankAccountInput!) {
  getPlaidBankAccountBalance(input: $input) {
    platformItemId
    bankInstitutionAuthId
    bankAccountId
    amount
    current
    source
    trigger
    startedAt
  }
}
```

```json theme={null}
{
  "input": {
    "bankAccountId": "bank-account-id"
  }
}
```

For all of the user's connected accounts:

```graphql theme={null}
query GetPlaidBankBalances($input: PlaidBankBalanceFilterInput) {
  getPlaidBankBalances(input: $input) {
    platformItemId
    bankInstitutionAuthId
    bankAccountId
    amount
    current
    source
    trigger
    startedAt
  }
}
```

## Refresh one account in realtime

Request a rate-limited realtime balance refresh for a single bank account. This pulls a fresh balance from Plaid and updates the balance-derived spend power.

```graphql theme={null}
mutation RefreshPlaidBankAccountBalance($input: PlaidBankAccountInput!) {
  refreshPlaidBankAccountBalance(input: $input) {
    status
    balances {
      bankAccountId
      amount
      current
      source
      trigger
      startedAt
    }
  }
}
```

```json theme={null}
{
  "input": {
    "bankAccountId": "bank-account-id"
  }
}
```

### Refresh rate limit

To control cost, realtime refreshes are rate limited **per Plaid institution**: one realtime refresh per hour and six realtime refreshes per day. A refresh requested inside a limit window does not call Plaid again — it returns the latest stored balance instead, so the call still succeeds and returns data. Design your UI so that a returned balance is not always assumed to be a brand-new realtime reading.

## Refresh all connections (cached)

Request a cached refresh of all connected Plaid bank data for the authenticated account.

```graphql theme={null}
mutation RefreshPlaidBankConnections {
  refreshPlaidBankConnections {
    status
    balances {
      bankAccountId
      amount
      current
    }
    verifyMembers {
      platformItemId
      bankInstitutionAuthId
    }
  }
}
```

Use `refreshPlaidBankConnections` when you want identity-service to perform its cached all-connection refresh.

> If `verifyMembers` is returned, one or more connections need repair. Use the `platformItemId` to start the relink flow — see **Relinking Disconnected Bank Accounts**. Note that the single-account `refreshPlaidBankAccountBalance` mutation does **not** return this signal, so use `refreshPlaidBankConnections` when you need to detect disconnected connections.

<br />