How to Communicate a Breaking Change Without Losing Customers

Every SaaS that survives long enough ships a breaking change. Auth models evolve, pricing tiers restructure, APIs get redesigned, a data model turns out to be wrong. The breaking change itself is rarely the problem. What churns customers is the communication around it — a surprise email on a Friday, an endpoint that returns 410 Gone with no warning, a pricing change announced three days before it applies.

This playbook is the operational manual: how to classify the change, how to time the announcement, who to notify in what order, and three copy-pasteable templates for the inevitable emails. Written from post-mortems of breaking changes that went well and breaking changes that didn't.

TL;DR

• Classify the change first. Three buckets: breaking, additive, fix. Only breaking triggers this playbook.
• Announce T-90 days for material changes, T-30 for trivial ones. Never less than 14.
• Four touchpoints: T-announcement, T-reminder, T-last-chance, T-zero. Plus T+14 post-mortem.
• Notify in order: CSMs → Support → Technical contacts → All affected users. Not simultaneously.
• Ship templates your whole company can use. Improvising on the day is how you get into the Register.

What counts as a breaking change

A breaking change is anything a customer has built around that will stop working the way they expect it to. That definition is deliberately broader than the engineering one.

| Change | Is it breaking? | |---|---| | Removing an API endpoint | Yes | | Changing a pricing plan's credit allocation down | Yes | | Renaming a dashboard menu item | Usually no — but flag if trainings or SOPs reference it | | Changing a webhook payload's field names | Yes | | Moving a feature from Pro to Enterprise | Yes | | Tightening rate limits | Yes | | Adding a new optional field to an API response | No (additive) | | Fixing a bug that customers had built around | Yes — "silent-breaking fix" | | Removing a dead-end UI flow nobody uses | Check analytics; if under 0.1% of users, usually no |

The tie-breaker question: Can a reasonable customer be doing the thing today and find it not working next month? If yes, it's breaking. Err toward breaking — a false positive costs you an email; a false negative costs you a renewal.

The 90-day timeline

Use this as the default for any material breaking change. Compress for trivial changes, but never below 14 days.

T-90: Announcement

The first moment any external surface mentions the change. On this day:

• Publish the changelog entry with the exact date of the change and the migration path.
• Send the announcement email to all affected technical contacts and CSMs.
• Post an in-app banner to affected users' dashboards.
• If API: start returning Deprecation and Sunset response headers on the affected endpoints.
• Open a public GitHub issue or docs page for ongoing Q&A.

T-60: Reminder

A second, lighter-touch nudge. Many technical contacts will have triaged the first email to "later". This is the nudge that moves it from later to now.

T-30: Last-chance

Tone shifts from informational to urgent. Include a concrete status check: "According to our logs, you still have X% of traffic on the deprecated endpoint." Surface a status page or dashboard tile that lets them verify themselves.

T-0: Cutover

The change ships. On this day:

• Send a short email confirming the change is live.
• Keep the old behavior running for 14-30 days behind a feature flag or version header if technically feasible — the T-0 date is the behavioral cutover, not necessarily the code removal.
• Monitor error rates on the migration and have a rollback path ready for the first 24 hours.

T+14: Post-mortem

The last touch, and the one most teams skip. Send a short note: what shipped, what we learned, what we'd do differently. Attach a revised playbook if relevant. This converts a breaking change — which is anxiety-inducing for customers — into a trust-building moment.

Who to notify, and in what order

Parallel notification is how breaking changes turn into PR incidents. The support team finds out from a customer ticket at the same time the customer finds out from the email. Neither can help the other.

Stagger the waves by 24–48 hours:

1. Internal first — CSMs, Support, Sales Engineering. They need 48 hours to prep responses, update playbooks, and flag at-risk accounts. Give them the exact email the customer will receive.
2. High-touch accounts second — Enterprise customers with named CSMs get a personal call or Slack before the mass email. This is a retention lever, not a courtesy.
3. Technical contacts third — The email to the engineering or ops contact on the account. This is the person who will actually do the migration work. They get the technical detail, the migration path, and a link to the migration guide.
4. All affected users last — The in-app banner and secondary email, to any user whose workspace is affected. This is lower-detail, more benefit-framed. Link back to the full technical notice.

Sending the mass email first and briefing CSMs afterwards is how you lose accounts that were otherwise happy. The timeline is an order, not a list.

Three templates to copy

Template 1: T-90 announcement email (technical contact)

Subject: Breaking change on [endpoint/feature] — action required by [date]

Hi [name],

We're writing to let you know about an upcoming breaking change on
[ReleaseGlow | your product]. Your account's integration is affected.

What's changing
[One sentence on the behavior change. No jargon, no marketing copy.]

When
The change takes effect on [YYYY-MM-DD], which is [N] days from today.

Why
[One or two sentences on the motivation. Compliance, performance, security,
or product direction.]

What you need to do
[Bullet list of the migration steps. 3-5 items max.]

Migration guide
[Link to a dedicated docs page with code samples.]

Your status
We see [N] requests per day from your account on the affected
[endpoint/feature]. Most recent activity: [date].

Questions
Reply to this email or open an issue at [link]. We'll respond within one
business day.

Thanks for building with us.
[Your name], [Title]

Template 2: In-app banner copy

[Warning icon] Heads up: [feature] is changing on [date].
Your workspace uses it [N] times per week. [Learn what's changing →]

Keep the banner under 140 characters. Link to a longer page. Dismissible but reappearing for users with affected traffic.

Template 3: T-30 last-chance email

Subject: 30 days left — [endpoint/feature] migration

Hi [name],

This is a reminder that [feature/endpoint] is changing on [date]. That's
30 days from today.

Your current status
According to our logs, you still have [N] requests per day on the
deprecated [endpoint/version]. See your migration dashboard for live
numbers: [link].

If your migration is complete
You may still see legacy traffic from cached clients or retries. Those
will start failing on [date] with [error code]. No action needed on your
side beyond confirming zero traffic on the old path.

If your migration is not complete
Reply to this email and we'll set up a working session with our
engineering team. We've helped 40+ customers through this same migration
and can usually unblock in under 30 minutes.

Thanks,
[Your name]

Big-bang vs phased cutover

When the old and new behavior can technically run in parallel, you have a choice. Each has real trade-offs.

Default to phased for anything touching revenue or authentication. Default to big-bang for changes where the dual-maintenance cost is material and you've already given 90+ days notice. Never big-bang on a Friday.

The post-mortem nobody writes

Two weeks after the cutover, send a short note. Not marketing, not apologetic — informational. Three bullets:

• What shipped, on what date, with what result (error rates, open tickets, churn signal).
• What we learned (something we'd warn about earlier next time, or a tool we'd ship).
• What we'd do differently (shorter timeline, earlier CSM brief, different channel mix).

This email costs an hour to write. It dramatically shifts how customers remember the breaking change — from "they broke our integration" to "they handled it well". That's the difference between a support ticket that mentions the migration and a renewal conversation that mentions the migration.

Common pitfalls

Hiding the word "breaking"

Marketing wants "improvement". Legal wants "update". Both are wrong. The word breaking goes in the subject line, the banner, the changelog entry, the docs page. Customers scan for it. Hiding it is how you get the Friday support spike.

The 14-day "plenty of time" trap

Even trivial breaking changes should get 14 days. Technical contacts take vacation, accounts get reassigned, tickets get triaged to "later". 14 days is the floor; 30 is the default; 90 is for anything material.

Skipping the non-technical stakeholders

The technical contact migrated the code. Nobody told the finance team that invoices will now have a different line-item format, and now procurement is escalating. Breaking changes often have second-order effects — tax reporting, audit logs, compliance reviews. Loop in account owners, not just engineers.

Launching on a Friday

Don't. Tuesday–Thursday, early enough that your on-call team is awake, with at least 24 hours of business-hours support after the change. The number of Friday-afternoon deprecations that ended in a Monday-morning incident is larger than it should be.

No status tile for customer self-service

Every breaking change should ship with a status tile in the customer's dashboard: "Your account's status on the [X] migration: 87% migrated, 3 endpoints remaining." Customers who can check themselves don't file tickets.

FAQ

Wrap-up

A breaking change isn't the risk. An unannounced breaking change is the risk. A poorly-timed one is the risk. A breaking change that hides behind "we've made some improvements" copy is the risk.

Classify, date, template, stagger, post-mortem. The discipline isn't complex — it's just rarely held. Teams who hold it can ship breaking changes as routine operations, with zero churn impact. Teams who don't treat every migration as a five-alarm fire, burn through CSM goodwill, and eventually stop shipping the right changes at all.

Ship the playbook to your whole company once. Update it after every breaking change. The hundredth one will be boring.