Wallet balance types

A Flexprice wallet exposes two distinct balance values: Current Balance and Ongoing Balance. They answer different questions and are used by different parts of the platform. Knowing which one you are reading prevents alert misconfiguration and surprises when reconciling usage against credits.

​

At a glance

​

Current Balance

Current Balance is the settled credit balance of the wallet. It changes when a transaction completes — for example, a top-up is paid, a manual debit is applied, or an invoice that draws from the wallet is finalized. It does not move while usage is accumulating during a billing period. Use Current Balance when you need a stable, audit-friendly number — for example in finance exports, reconciliation reports, or the wallet ledger.

​

Ongoing Balance

Ongoing Balance is the real-time view of what the wallet has left after accounting for activity that has not yet settled. It starts from the Current Balance and subtracts:

• Pending invoice amounts — invoices that are finalized but not yet paid and will draw from the wallet.
• Current period usage — usage events ingested in the active billing period that will be billed against the wallet.

Ongoing Balance is what powers entitlement decisions, low balance alerts, and auto top-up. It is the number to read when you want to answer “does this customer have enough balance to perform this action right now?”.

​

Which balance triggers alerts

Different alert and webhook events read different balances. Pick the event that matches the behavior you want.

​

Reading balances

Both values are returned by the wallet read APIs and surfaced in the customer dashboard. When you build internal dashboards, gate actions on Ongoing Balance; when you build accounting views, prefer Current Balance.