Spend Accounts
A spend account is a cash balance account inside Fluz that a user uses to hold, organize, and track funds. Each account has its own nickname, so a user can separate spending by purpose — for example "Team Travel," "Operations Wallet," or "Marketing Budget" — and every account keeps its own running balances.
Spend accounts are the wallet that everything else draws from: they hold the funds used to purchase gift cards, fund virtual card transactions, and receive deposits and transfers.
"Spend account" and "cash balance account" are the same thing.In the API, a spend account is represented by the
UserCashBalancetype, and the operations are named...UserCashBalance(e.g.,createUserCashBalance). This page uses "spend account" throughout.
Balances
Every spend account tracks three balances, all returned as strings:
| Balance | Field | Description |
|---|---|---|
| Total | totalCashBalance | The full balance currently held in the account. |
| Available | availableCashBalance | The portion available to spend immediately. |
| Lifetime | lifetimeCashBalance | The cumulative total of all funds ever deposited into the account. |
A user can hold multiple spend accounts, and one is flagged as the default (isDefault: true).
What You Can Do
| Action | Query / Mutation | Scope | Description |
|---|---|---|---|
| Create a spend account | createUserCashBalance | MANAGE_PAYMENT | Open a new spend account with a custom nickname. |
| Get spend accounts | getUserCashBalances · getUserCashBalanceById | LIST_PAYMENT | List all spend accounts (with filtering and pagination) or fetch one by ID. |
| Edit a spend account | updateUserCashBalance | MANAGE_PAYMENT | Rename a spend account (nickname, 2–100 characters). |
| Close a spend account | closeUserCashBalance | MANAGE_PAYMENT | Close an account, move its remaining balance, and handle any dependent virtual cards. |
Account Lifecyclespend account moves through a small set of statuses (UserCashBalanceStatus): typically ACTIVE, and CLOSED once closed.
UserCashBalanceStatus): typically ACTIVE, and CLOSED once closed.Closing an account is more than a status change. When you close a spend account with a remaining available balance, that balance must be moved to another spend account. If any virtual cards are funded by the account being closed, you must either reassign them to a new funding source or lock them as part of the same request.
Closing an account requires you to resolve its balance and dependent cards.If the account still holds an available balance, provide
transferUserCashBalanceIdto move it. If virtual cards are tied to the account, provide eithernewFundingSourceto reassign them orlockAllVirtualCardsto lock them. See Close Spend Accounts for the full input reference.
How Spend Accounts Fit Ind accounts sit at the center of a user's wallet:
- Fund them with Deposit Funds or move money between them with Transfer Funds Internally.
- Spend from them on gift cards and virtual cards.
- Check balances anytime with Check Account Balance or the spend account queries above.
Requirementsg spend accounts requires the LIST_PAYMENT scope. Creating, editing, and closing spend accounts require the MANAGE_PAYMENT scope. Make sure your user access token carries the correct scope before calling these operations.
LIST_PAYMENT scope. Creating, editing, and closing spend accounts require the MANAGE_PAYMENT scope. Make sure your user access token carries the correct scope before calling these operations.Want to learn more? Speak with our experts for more info or to request a demo.