Playbook, developer tools company
The first sign of a billing problem is a status code at four in the morning
On a product sold to engineers a payment failure does not surface as a banner somebody eventually notices. It surfaces as rejected calls in a running system, at whatever hour the last retry gave up, in front of an on call engineer who has no idea there is a billing problem and no access to check. The distance between the finance mailbox and the pager is the thing worth writing down.
Why this is not the general answer
The handling pattern for failed payments holds across every trade. What follows is the part that does not.
- The consequence lands in the customer's own monitoring rather than in anybody's inbox, so the first person to find out is on call, has no billing access and has no reason to suspect the account at all.
- The failure has a specific shape on the wire, a status and a message, and if that string appears nowhere in your documentation the reader spends the first hour debugging their own client instead.
- Notices go to a billing address registered when the account was opened, which on a technical account is frequently an alias nobody reads, so a grace period can elapse without a single person hearing about it.
- Whether service degrades gradually or stops outright is an engineering decision with a date attached, and publishing that date is worth more than any reassurance, because somebody has to plan a deployment around it.
How it arrives
- our calls started returning 402 overnight
- how long after a failed charge do credentials stop working
- does it degrade first or just stop dead
- which address do your billing notices go to
- we updated the card do we need to do anything to restore service
- can we get service back before the payment clears
What has to be indexed for this to work
| What a billing suspension looks like to a client | The status, the exact message, and whether it differs from an ordinary authentication rejection. Without this the reader debugs their own code first, and that hour is what turns an inconvenience into a complaint. |
|---|---|
| The retry schedule and the suspension date, as a sequence | How many attempts, how far apart, what goes out at each, and the day service changes. It is a set of fixed rules and it is almost never published, which is exactly why the same message keeps arriving. |
| What continues to work during the grace period | Whether reads continue, whether scheduled work still runs, whether exports are possible. The anxiety underneath the question is whether something in flight is about to be lost, and a list of what still functions answers it directly. |
| Who may change the payment method, and the exact route | The role required and the screen. On a technical account the person who registered the card has frequently moved on, so name the route for moving that role as well as the route for changing the card. |
The reply
A billing suspension returns its own status and message rather than an ordinary authentication rejection, and the exact string is in the error reference so you can tell the two apart in your logs [1]. The retry schedule and the day service changes are published with the billing terms, and during the grace period the behaviour described there applies rather than a hard stop [2]. The payment method is changed by whoever holds the billing role, and where that person has left, the same page covers moving the role to somebody else. I cannot see a payment, retry one or restore anything, so leave your name, the account email and the organisation and the team will pick it up.
It leads with the string in the logs, because the reader is staring at an alert and needs to stop suspecting their own client. The schedule follows, since the actual question is how much time there is. Naming the role, and the case where that person has left, resolves a large share of these outright, and the refusal lists three concrete things rather than gesturing at a general limit.
Where it stops
The trigger. The reader asks for service to be restored, for a payment to be retried, or says the card has been updated and calls are still being rejected.
Restoring service and retrying a payment both need somebody who can open the account, and I can do neither. Leave your name, the account email, the organisation and roughly when the rejections started, and it goes over with all of that.
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 a payment has gone through, been retried, or that service has been restored.
- Never grant a grace period, an extension or a hold, because only the team can agree to one.
- Never explain why a particular card was declined, as that sits with the issuer and is not visible from here at all.
- Never say traffic will keep working past a date the published schedule does not promise.
Questions
- Why does the error string matter so much in this pair?
- Because the first responder is an engineer rather than a finance manager. If a suspension looks identical to a bad credential they will rotate keys, redeploy and read their own code before anybody thinks to check the account, and each of those is an hour.
- Can it check whether our payment has cleared?
- No. It holds no view of billing whatsoever. It can state the schedule and the suspension date, which is what people are counting towards, and take the details so somebody can look at the actual attempts.
- Should the technical contact be notified as well as the billing one?
- That is a product decision rather than a documentation one, and it is the fix for this whole category. Whatever you settle on, publish which address receives what, because the assumption that somebody was told is what turns a suspension into an argument.
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 failed payments in generalThe reason usually sits with the card issuer and is invisible to you. The useless reply, the useful one, and why card details never belong in a chat.
- The interface is a terminal, so the usual accessibility answers do not applyColour as the only signal in output, a keyboard driven interface and code blocks read aloud. These arrive as defect reports, not form problems.
- Can we get into the beta is a request rather than a questionEarly access programmes, regions that are not open yet and a library for a language nobody has written. What can be said without committing anyone.
- The deploy window is at night and nobody is at a deskChange windows and incidents both happen at night. What can honestly be answered overnight, and how a severity definition decides who is woken.
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.