The Bill Is Authorised by Delivery, Not by Your Spend

We built a metered API on top of a paid vendor, and at some point every one of us thought the same thing: we already paid for this, so we have to charge for it.

It is an intuitive sentence. It is also wrong, and the specific way it is wrong cost us a customer 900 credits for a video that was never produced. We set out the four outcomes when we first got this right.

We fixed the code. Then the sentence came back into our own documentation. Twice. That is the part worth writing about: not the bug, but why a rule that everyone agrees with keeps getting quietly reworded into a rule nobody would agree with.

The wording that keeps returning

It comes back in this shape:

If the run failed after a paid vendor call, we charge.

Read it quickly and it sounds like fairness. We are out of pocket, so the cost is passed on. Read it as a specification and it says: once money has left our account, the client owes us something regardless of what they received.

That is what produced the 900-credit charge. A run got far enough to pay a vendor, failed, and the rule said charge. There was no video. The number was derived from the script's estimate, because there was no finished clip to measure. The client was billed for something that did not exist, and the code was doing exactly what it had been told.

The rule that replaced it

The bill is authorised by delivery, not by our spend.

The right to charge comes from the video work having been dispatched to the vendor — from supplying work — not from money having left our account somewhere along the way.

The distinction sounds academic until you apply it to two real runs.

Run A: we paid for speech, the vendor refused to create the video. We spent money. The speech synthesis was billed to us and cannot be recovered. The client receives nothing. Charge: zero. Our spend is our cost of doing business, not their obligation.

Run B: we paid for speech and the vendor accepted the video job. The supplying work was dispatched. Charge: the measured length of what came back.

The difference between those two runs is not how much we spent — Run A may have cost us more than a short Run B. It is whether the work that produces the deliverable was actually sent.

Four outcomes, not three

Being precise here matters, because our own internal documentation got it wrong and that is how the bad wording found its way back in.

1. Failed because of us → charge nothing, even when the vendor was already paid. Our spend guard tripped, our storage lost a paid file, the vendor refused on our own account, or we rejected an unusable take. Four distinct causes, one outcome.
2. Succeeded → charge the measured length of the finished clip.
3. Failed after the video work was dispatched → charge. Without a measured length, the charge falls back to an estimate from the script.
4. Failed before that point → charge nothing. This is the band Run A lives in.

Outcome 1 is checked first, and the ordering is deliberate. A vendor refusal on our own account happens after dispatch, so a reader walking the list top-down would otherwise land on outcome 3 and charge for it. Our side settles before anything else is considered.

Our written rule listed three causes under outcome 1. The code checks four. The missing one is our own rejection of an unusable take.

Nothing was ever mis-billed by that gap, because the outcome is identical for all four causes. But the document is what people read when they rewrite the billing rules, and a document that enumerates incompletely invites someone to reconstruct the rule from what is there. It is a plausible route back to "we paid, so we charge": if you only see three causes and none of them is the one in front of you, the general principle is the thing you fall back on, and the general principle is the one we are trying to replace.

We have filed that as its own defect. The code is the source of truth; the document had drifted into being a lossy summary of it while still reading like a specification.

Why this class of rule rots

Three properties, and most billing rules have all three.

The wrong version is shorter. "Failed after a paid call, we charge" fits in a sentence. The correct version needs four cases and a distinction between spending and dispatching. Every edit that makes documentation more concise applies pressure in exactly one direction.

The wrong version is locally reasonable. Nobody reintroduces it maliciously. They encounter a case where we paid and got nothing, feel the unfairness, and write down the rule that fixes the case in front of them.

Nothing fails when it drifts. Reword the document and every test still passes, because the tests are against the code. The drift only surfaces when someone implements from the document — which is precisely when it is expensive. This is the same shape as an agent reporting success for work that never landed: the artefact says one thing, the system does another, and nothing in between raises its hand. It is also why an unmet parameter has to be named rather than absorbed.

The check worth stealing

Any wording of your billing rule has to answer both runs above. If a proposed sentence cannot produce zero for Run A and measured length for Run B, it is wrong, however reasonable it reads.

That is a two-line test that fits in a pull request description, and it is the thing we now paste into the conversation whenever someone proposes tightening the wording. It is faster than re-deriving the principle, and unlike the principle, it is hard to accidentally soften.

FAQ

Why charge an estimate when the run fails after dispatch?

Because the alternative is worse in both directions. The vendor has been given the job and will bill for it, so charging nothing makes a failed render free to trigger repeatedly. But there is no finished clip to measure, so an estimate from the script is the only number available. It is the one place the system knowingly bills on a number it did not measure, and it is bounded by the script length rather than by anything open-ended.

Is not "we rejected the take" a judgement call you could abuse?

It is a judgement call, which is why it lands in outcome 1 and costs the client nothing. The incentive runs the right way: rejecting a take is pure cost to us. A rule where our own quality rejection were billable would be a rule worth distrusting.

How do you keep the document from drifting again?

We are treating the enumeration as the thing under test rather than the prose around it. The deeper answer is that a document which restates a rule the code already encodes will drift, and the fix is for it to point at the code rather than paraphrase it. Paraphrase is where the loss happens.