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.

Authorization: Bearer <fluz-user-access-token>

Get spend power for one bank account

query GetPlaidBankAccountSpendPower($input: PlaidBankAccountInput!) {
  getPlaidBankAccountSpendPower(input: $input) {
    bankAccountId
    spendPower
    availableSpendPower
    lastRecordedBalance
    pendingTransactions
    updatedAt
  }
}

{
  "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:

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

{
  "input": {
    "bankAccountId": "bank-account-id"
  }
}

For all of the user’s connected accounts:

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.

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

{
  "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.

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.

​What spend power means

​Auth

​Get spend power for one bank account

​Get the latest stored balance

​Refresh one account in realtime

​Refresh rate limit

​Refresh all connections (cached)