Playbook, developer tools company
An engineer has been asked to explain a spike to somebody in finance
The invoice is the first time anybody sees the month as a total. It is itemised in units rather than in things a finance team recognises, it is larger than the last one because of something that happened at three in the morning on a Tuesday, and the person told to explain it is the engineer who wrote the client. What they need is the definition of the line and the place the counter lives, not reassurance.
Why this is not the general answer
The handling pattern for billing and invoices holds across every trade. What follows is the part that does not.
- The lines are counts of consumption rather than named products, so an invoice cannot be read without the meter definition beside it, and those two documents almost never live in the same place.
- A spike has a mechanical cause with a timestamp attached: a client retrying without backing off, a scheduled job whose interval changed, a backfill somebody started on a Friday. The reader is hunting for the hour, not the total.
- The document is addressed to a company, with a purchase order reference, a tax registration and a legal entity that is frequently not the one the engineer works in, and none of that is anything an engineer holds.
- Usage shown inside the product and usage on the invoice are aggregated over different windows and rounded differently, so they disagree, and a written explanation of why is what stops that being reported as a fault.
How it arrives
- why is this month three times last month
- what exactly is one unit on this line
- can we get a purchase order number printed on the invoice
- does the usage graph match what we are billed for
- we need the invoice made out to our parent company
- can you break the bill down by key or environment
What has to be indexed for this to work
| A glossary of the invoice lines, in the wording actually printed on the document | Every line as it appears, and what generates it. Written in the printed wording rather than in internal names, because the person reading is holding the document and matching strings against a search box. |
|---|---|
| How the meter aggregates, including the window and the rounding | Whether usage is summed hourly or daily, the moment a unit is recorded, and how partial units round. This is the document that explains why the counter in the product and the figure on the invoice differ, and without it that gap is read as an error. |
| Whether consumption can be attributed by key, project or environment | Teams want a staging spike separated from a production one. If your billing does not break down that way, publish that, because otherwise people spend an afternoon looking for a screen that was never built. |
| The billing details you can put on a document, and who has to ask | Purchase order references, tax registration numbers, the entity name, and the route for a reissue. A finance team blocks payment on any one of these and the engineer forwarding the request has no idea which one is missing. |
The reply
Each line is a count of billable units for the period, and the meter reference defines exactly what increments it [1]. Usage inside the product is aggregated hourly while the invoice sums whole days, so the two are expected to differ at the edges rather than agree to the unit [2]. Where a month is much larger than the one before it, the ordinary mechanical causes are a client retrying without backoff and a scheduled job whose interval changed, and both show as a narrow spike rather than a raised floor, which is what to look for in your own graphs. I cannot open an invoice, read your usage or break a bill down, so leave your name, the account email and the invoice reference and somebody will go through it with you.
It hands over the two documents that let the reader do the reconciliation they were asked to do, rather than doing it for them badly. Naming the aggregation difference before they discover it prevents an accusation of a billing fault. The two causes are offered as a shape to look for in their own monitoring, which is a suggestion rather than a diagnosis, and that distinction is the whole reply.
Where it stops
The trigger. The reader quotes a figure from their own invoice, asks for a document to be reissued or readdressed, or asks for a purchase order or tax reference to be added.
Anything to do with the document itself, reissuing it, readdressing it or adding a reference, needs somebody who can open the account. Leave your name, the email the account is under and the invoice reference, and it will reach them with all of that attached.
It stops answering before it guesses, says who will pick it up, and asks for the one thing that makes a reply possible. Nothing about it reads as a dead end.
Never say this here
Out of bounds
- Never say what a specific invoice contains or what an account has consumed, because nothing here reads either.
- Never say a charge is wrong, or that a spike was produced by a fault on your side.
- Never agree that a document can be reissued to a different entity, since that is a finance decision with tax consequences attached.
- Never quote a meter definition or an aggregation window that is not in your own published reference.
Questions
- Can it break a bill down by key if we ask it to?
- No, and it cannot read the bill in the first place. What it can do is say whether your billing supports that breakdown at all, which is the real question underneath, and one that otherwise costs somebody an afternoon of looking for the screen.
- Our usage graph and our invoices genuinely disagree. Should we publish that?
- Yes, with the reason. Two numbers that differ with a published explanation are a rounding note. The same two numbers with no explanation get discovered mid reconciliation and reported as a billing fault, which you then answer one message at a time forever.
- A lot of these come from finance rather than engineering. Does the wording change?
- The vocabulary does. Somebody chasing a purchase order reference does not know what a unit is and should not have to learn. Keep the line glossary in the exact words printed on the document, so a search for the line as written actually finds it.
Keep reading
- Everything for a developer tools companyOn a docs site an assistant competes with search, not a phone line. Version skew, deprecations and error strings decide whether it earns its place.
- Handling billing and invoices in generalInvoice copies, tax numbers, purchase order references. Nearly all of it is account specific, so the honest handling is process plus a clean handover.
- Two deployments, and two completely different answers to delete our dataFor a self hosted install there is nothing on your side to delete. For the hosted one, request logs and telemetry each run their own clock.
- An engineer has been handed a review and does not own the answersAudit logs, retention windows and release provenance. What can be answered from published trust material, and which rows need an agreement.
- Access problems where half the accounts do not belong to anybodyMachine identities, organisation membership and credentials shown only once. Access questions where the actor is a process rather than a colleague.
Try it on your own material
Upload a document or point it at your site, paste one line of HTML, then ask it something only your business could answer.