Skip to main content
Some releases change what a customer sees on an invoice or in a portal. Those need a notice, and a notice that is vague is worse than none.

​
The rule

Say the number, say the direction, say the date. A customer told “some figures may change slightly” reads it as noise and rediscovers the change through a finance query three weeks later. A customer told “your March invoice will be about 18% higher and here is why” can plan.
Never describe a correction as an improvement.These notices are fixes to defects, and in each case the customer was on the wrong side of the defect in at least one respect. Writing around that is precisely what destroys the trust the notice was sent to protect.
Send from the platform’s own address to the account’s billing contact, not through the portal. An in-app banner reaches whoever next signs in, which on a machine-to-machine account is nobody. app_account.email is the contact of record.

​
The ratio almost everyone gets wrong

When a fix means retried messages start being counted, the customer’s figures rise. The size of that rise is not retried / total. Their old figure was the non-retried traffic alone — so the step from what they saw to the truth is measured against that, not against the total.
At a 20% retry rate the figures rise by 25%, not 20%. Quote pct_count_rises, never pct_of_traffic — they are different questions and the gap widens as the retry rate goes up.

​
Finding who is affected

Spend gets its own column rather than borrowing the message one, because retried traffic is not priced like the average — it is whatever destinations and products happen to be failing. An account whose retries are concentrated on an expensive route sees a bigger money rise than message rise. part_no = 1 because the money lives entirely on part 1 of a concatenated message.

​
Two sentences that must not be softened

Whatever else is rewritten to suit your platform’s voice, these survive intact:
When a fix raises a customer’s visible figures towards their invoice, the customer’s numbers were below what they were billed.A customer told their numbers are changing without being told which side was wrong reasonably assumes they have been overbilled — and every one of them asks. Saying it up front is cheaper than answering it thirty times.
Never worded as “no limit” in anything sent outside.There is no representation of unlimited anywhere in the system, deliberately: a typo that reads as unlimited gives away a month of traffic nobody can invoice for.

​
A notice that works

1

What is changing, in one sentence

In the customer’s terms — “the message counts in your portal”, not “the CDR aggregation”.
2

The number, for them specifically

From the query above. A per-account figure beats a platform average every time.
3

Which direction, and whether money moves

Say explicitly if invoices are unaffected. Assume they will otherwise conclude they were overbilled.
4

The date it takes effect

So they can align it with their own reporting period.
5

What they need to do

Usually nothing — say so, rather than leaving them to work it out.

Migrating a deployment

The changes that need a notice in the first place.

Statements

Why a closed period is never restated.