Balance and usage plugins: when credit hits zero

Balance, usage and billing are not the same thing. One shows what is left, one shows what was spent, and one turns spending into money. Mismatches are normal because the sources differ.

What each type covers

Establish the data source before arguing about accuracy.

Balance is an external query. It depends on the endpoint and a key; when the endpoint is unreachable the number freezes.

Usage is local accounting. It is computed from session records, so deleting or cleaning sessions alters history.

Billing is local conversion. You supply the price table; if prices changed and the table did not, the total drifts (source).

Three ways to continue at zero

A plugin reports credit; it cannot create it.

1. Switch models: move to another model or provider with remaining credit and keep the task going.
2. Run locally: configure Ollama or a similar local model for offline inference that consumes no account credit.
3. Wait or top up: allow the quota to reset or add credit, which is account-level work.

Save context before switching. Window size and capability differ, and a long session may be compacted; record the conclusions first.

A local model is a stopgap. It rescues the moment, but quality and speed may trail the cloud; complex work should return to a funded model.

Configuring a billing plugin

Accurate billing rests on an accurate price table.

1. Enter input and output prices for the current model, including cache pricing.
2. If peak pricing is supported, configure per-window prices (source).
3. Choose the accounting scope: per session or per time window.
4. Decide whether tool calls and subagent usage count.
5. After each change, run a comparison round and confirm the total moves as expected.

The price table is configuration, not a subscription. When a provider changes prices, the plugin does not follow; you edit it.

Keep the accounting scope fixed. Switching between per-session and per-day makes numbers incomparable; choose one and keep it.

Auditing a bill

When numbers disagree, check three error sources.

A stale table is the most common. After a price change, the old table keeps computing at old rates, so the total cannot match.

Peak and cache pricing come second. Ignoring time windows and cache hits produces systematic drift; platform bills usually carry both lines.

Missing scope hides best. Tool calls and subagents consume tokens too; reading only the main conversation underestimates the bill.

Audit by sampling. Take one session, compare the platform bill with the plugin total, and note how much and where it diverges. Sampling is faster than a full reconciliation.

Keys and privacy

Balance and billing plugins touch keys and usage data, so keep permissions narrow.

1. Minimum privilege: issue a key that can only read balance or usage.
2. Trusted source: prefer plugins with complete documentation and recent updates.
3. No conversation upload: a correct implementation queries balance only, not chat content; read the description first.
4. Local storage: cost records usually live locally, so note whether cleaning sessions deletes them.
5. Shared machines: allocate keys per person so nobody sees another person's balance.

A leaked key costs more than a visible balance. When unsure, skip the plugin and read the provider console.

Isolate shared environments first. Balance is account-level information; decide who may see it before installing.

Troubleshooting

Four failure classes cover most balance and billing problems.

1. Frozen number: expired key, unreachable endpoint, or a long refresh interval.
2. Large money gap: stale price table, missing peak pricing, or a missing scope.
3. History reset: sessions were cleaned or the data directory moved.
4. Plugin invisible: wrong profile, disabled switch, or a hidden interface slot.

The entry points are endpoint, configuration and data. Confirm the endpoint answers, then the configuration, then whether records are complete.

Trust the provider console. When plugin numbers disagree with the platform, the bill wins; the plugin is an observer, not a ledger.

Next steps

Separate the three types, then configure what you need. For widget forms, read Which whale widgets exist. For usage plugins, read Usage tracking plugins. For balance plugins, read Balance and cost plugins.

Sources: dsh-cost-meter plugin page (nanako660), dsh-cost-meter plugin page (creakono), DeepSeek Harness documentation