One Source of Truth for Fair-Usage Limits

A fair-usage policy is a promise. Here is what your plan includes, and here is what it costs when you go past it. Writing that down is easy. Making it true means every system that computes against it gives the same answer, and that is the part nobody budgets for.

The chat platform I work on publishes nine usage bands keyed to annual spend. Each band includes five allowances, and going past any of them is billed as an overage: $5.00 per million stored messages, $100.00 per million stored channels, $0.40 per gigabyte of egress, $7.00 per million API calls, $2.50 per hundred thousand query-channel calls. All of it is published in the docs, so a customer can read the table, do the arithmetic and predict their bill.

Every number there is a commitment. Any system that computes a different one is a bug with a dollar value attached.

A sentinel in a public table

The top two bands are the complication. Two of their five allowances are negotiated per customer rather than fixed, so the published table shows them as “Custom”. Internally that needs a sentinel, and a sentinel is only safe when every consumer knows it exists: any code comparing a usage figure against a limit has to skip those metrics rather than treat the sentinel as a threshold.

That is the general hazard. A value one reader treats as “not applicable” and another reads as an ordinary threshold does not fail loudly. It gives you a confident, plausible, wrong answer, and it does it at the end of the range where the fewest records will show you the mistake.

One table, read live

Getting the table right was not the same as fixing the problem. Two copies that agree today are still two copies.

An early draft of the backend endpoint mirrored the Go table in Python, with a comment telling the next person to edit both. That is not a source of truth. So the bands and the overage rates moved into reference tables in the shared platform database, with an editing UI, and the finance side of the business owns the values directly.

The backend reads those tables live, cached for five minutes, with no local models and no copy of its own. The dashboard reads the backend. One ladder, three codebases and two languages between the people who set the numbers and the customer who sees them, and no step in that chain holds a duplicate it could edit on its own.

The cost is a runtime dependency where a constant used to be. That meant designing the unavailable case rather than discovering it: bands that cannot be resolved return a clear error, and missing rates degrade to an empty list instead of a broken page.

Guidance, not a cap

The part I would keep in any future version of this is the part that lets the rule be broken.

Plan limits default from the band, and a bulk tool can reset every plan back to its band figures. But a limit set off-band, above or below, is kept rather than clamped. Saving one asks for explicit confirmation, resolving the band from the price being submitted so it stays correct when the price changes in the same edit, and the deviation is recorded as a warning.

Negotiated exceptions are not policy violations. They are the business. A system that clamps them quietly reverses agreements someone made on purpose. The reconcile tool is deliberately not on a schedule for the same reason: a job that reset limits to their band every night would eventually erase a deliberate decision, and nobody would know which one.

What I learned

The engineering here is unremarkable. Some tables, an endpoint, a cache, a management command. The judgment is in deciding which number is the real one and then refusing to keep a second copy anywhere, including the copy that would have been convenient.

A useful test for any policy that spans systems: pick a number a customer could read off your public documentation, then count how many places compute it. If the answer is more than one, that policy describes what your systems happen to do, not a rule they follow.