# spend-meter: one ledger, price table and cap for model calls

spend-meter is a WordPress plugin for sites that call language, embedding, image or speech models through several plugins. It records every call (tokens, cost, purpose, caller) and answers one question before each call: may this spend? The code is at [https://github.com/IndianOpinion/spend-meter](https://github.com/IndianOpinion/spend-meter), licensed MIT. Version v0.1.0 was released on 15 November 2026.

We wrote it from scratch from an idea, not from any third-party plugin. It has not run on a live site. The 47 utilities in this series were specified, built, reviewed and released between 11 and 19 November 2026 by language-model coding agents under the editor's direction, in five roles: a spec writer, a spec reviewer, a builder that saw only the spec, an independent code reviewer and a releaser. The editor made the rulings on every open question.

## The problem

WordPress does not say how much model calls cost, on what, or when to stop. The PRD lists what goes wrong without a shared meter:

- Each plugin logs usage in its own shape, or not at all, so nobody can answer "what did we spend today" without reading several tables.

- Caps live inside each plugin. A loop in one plugin can use the month's budget before its own cap, if it has one, notices.

- Price tables are hard-coded in plugin source. A model missing from the table gets a silent default, so the ledger is wrong without warning.

- Usage fields differ by API shape. A caller that reads one shape records zero tokens for the other.

- Callers that work out a call's cost by summing a shared table between two row ids also count other processes' rows when two requests overlap.

- A cap checked only after the call lets every concurrent process through.

## What it does

- Answers a pre-spend check with a machine-readable decision: allowed, or denied with a reason code.

- Records every attempt, billed or not, with tokens, cost, status and latency. A retry gets its own row.

- Enforces daily and monthly caps per site and per purpose, plus network caps on multisite.

- Offers a global kill switch and per-purpose kill switches, settable from the admin screen, WP-CLI or a constant the screen cannot undo.

- Holds an operator-loaded price table, with an as_of date and a source on every row.

- Normalises the two common usage shapes (input_tokens and prompt_tokens families).

- Shows a dashboard widget and a wp spend-meter command set (status, report, check, caps, kill, prices, reprice, reservations, export, prune).

## How it works

A caller plugin never depends on spend-meter. It asks through a filter and records through an action, and keeps its own cap and kill switch for when the meter is absent.

$decision = apply_filters('spend_meter_pre_spend', null, [
'purpose' => 'summary',
'caller' => 'my-plugin',
'provider' => 'example-provider',
'model' => 'example-model',
'est_input_tokens' => 1200,
'max_output_tokens' => 400,
]);
if (null === $decision) {
// No meter present: use your own cap and kill switch.
} elseif (true !== $decision['allowed']) {
return;
}

Inside, Decision runs the check in order: global kill switch, purpose kill switch, intent validation, ledger readiness, price and estimate, then the caps. A Ledger class does recording. The reservation step is the core of the design. An allowed check writes a reserved row holding the estimate before it reads the totals. Two processes racing near a cap each see the other's reservation, so both may be denied but neither overshoots. A false deny costs one retried call. An overshoot costs money.

Money is integer nanos (one billionth of the currency unit) everywhere. Prices are decimal strings converted with integer arithmetic, never floats. The cost of a recorded call comes from the first source that applies: the provider's reported cost, tokens priced from the table, the reservation estimate when no usage came back, or zero marked unpriced. When both a provider cost and a table cost exist, both are stored, so drift between list and billed price shows in reports.

A record settles its reservation in place. A second record on the same reservation (a retry) becomes a linked row. A record with no live reservation is inserted flagged unreserved, because the money was spent.

## Guard rails

- It fails closed. A missing ledger denies with ledger_unavailable. A decision filter that throws denies with decision_filter_error.

- No model with a price row, no call: unpriced models are denied by default. It ships the price format and no prices, so a fresh install denies every call until the operator imports prices or turns on "Allow unpriced models".

- The spend_meter_decision filter can add denials. An attempt to turn a deny into an allow is ignored and logged.

- Every check re-reads the kill switch and caps, so a long-running worker sees a change made in the admin screen.

- Recording never throws into the caller. A failed write is buffered (100 per request), retried at shutdown, then counted as a loss.

- No outbound HTTP, no API keys and no prompts stored. meta is limited to eight short scalar values.

- Admin saves check the capability and a nonce and validate every field. A price file with one bad row is rejected whole.

## What review changed

The independent code review found and fixed these before the merge:

- Unpriced models were allowed whenever no cap was set anywhere. They are now denied with unpriced_model by default.

- The 60-second network-cap cache held the whole network total, and each check added only its own estimate, so a burst on one site could pass the cap by any amount. The cache now holds the other sites' total, and each check adds its own site's live total.

- WordPress caches options per process, so a WP-CLI or queue worker would not see a kill switch or lowered cap until restart. Every check now drops the cached copy.

- A shutdown retry of a settle, whose reservation had been settled meanwhile, was silently dropped. It is now written as its own linked row. A settle that lost a race to a release is now filed as unreserved.

## Limits and what is next

- The meter counts what callers tell it. A plugin that never calls the filter is invisible, apart from unreserved records.

- The network cap can be passed by up to a minute of other sites' spend.

- One currency per install, with no conversion. No REST API in 0.1.0.

- The per-check totals query reads the site's month. In the design notes, on a test box with a 32 MB buffer pool and 256,000 synthetic rows, it took about 100 ms once the index covered it, against a 5 ms budget. The roadmap item is a per-day rollup table. A read-only REST route is the other roadmap item.

There are no open issues. This is v0.1.0, tested on stubs, mocks and a throwaway MySQL 8.0 server: 173 PHPUnit tests, 6 of them integration tests against that server. Static analysis and code style checks passed. CI has not yet run on GitHub: the commit adding the workflow stayed local because the token lacked the workflow scope.

## Install

It needs PHP 8.1 or later, WordPress 6.4 or later, and MySQL 5.7+ or MariaDB 10.4+. There is no Composer requirement at runtime.

The package is not on Packagist yet, so a Composer install needs a vcs repository entry for https://github.com/IndianOpinion/spend-meter first.

composer require indianopinion/spend-meter
wp spend-meter caps set site --day=<amount> --month=<amount>
wp spend-meter prices import my-prices.json --dry-run

Without Composer, unzip a release into wp-content/plugins/spend-meter/ and activate it. A must-use loader is in examples/.

[All 47 utilities](https://indianopinion.org/blog/open-source/) · [spend-meter on GitHub](https://github.com/IndianOpinion/spend-meter)

Canonical: https://indianopinion.org/blog/open-source/spend-meter/

AI disclosure: Every summary and comment here is written by AI and published automatically, without a person reviewing each article. We do no original reporting. How this works: https://indianopinion.org/ai-use-policy/
