How to Notify Customers About a Breaking Change

You searched for "how to notify customers about a breaking change" because you are about to do something your customers will not like. You have a deprecation date, a decision that is not reversing, and a support team that is about to get very busy. The question is not whether to tell them. The question is how to do it without torching the relationship.

Here is the counterintuitive part: done well, this can actually build trust. Customers have seen enough software evolve to know that breaking changes happen. What they cannot handle is being surprised, abandoned during the migration, or handed incomplete information. The communication plan matters more than the change itself.

Anyway. Here is how to run it.

Phase One: Before the Announcement Goes Out

The single most common mistake is announcing a breaking change before the migration resources exist. You cannot tell customers to move to v2 and then say "documentation coming soon." The announcement and the migration path have to ship together.

That means, before you send anything, you need: updated API references, a dedicated migration guide, side-by-side comparisons of old and new behavior, and a briefed support team. Your support team is not a detail. When the announcement lands, they will be hit immediately. They need FAQs, escalation paths, and a clear answer to the question every customer will ask first: "What happens if I don't migrate in time?"

On timing: for major API deprecations or infrastructure changes, the industry standard is a minimum of six months' notice, with many organizations recommending 12 to 24 months for critical systems. The right window depends on how much engineering effort the migration requires on the customer's side. If they need to schedule a sprint, they need to know before their next planning cycle.

There is also a technical layer that most teams skip. If you are deprecating an API endpoint, start returning a Deprecation HTTP response header before the external announcement goes out. The IETF formalized this in RFC 9745. Developers who are paying attention will catch it programmatically. Those who are not will still get the email. The header is not a substitute for communication; it is a signal layer on top of it.

Finally, decide who gets early notice before the public announcement. High-value enterprise customers should not find out from a mass email. Their account manager or customer success lead should have a private conversation first, giving them time to ask questions and plan their migration before the news is public. For customers who have not upgraded in years and are most likely to be caught off guard, you need a targeted outreach, not just inclusion in the general blast.

The Announcement Itself

The announcement must contain five things: what is changing, why it is changing, the exact deprecation date, the migration path, and where to get help. If any of those five are missing, the announcement is incomplete.

On the "what": be direct. Avoid vague language like "we're evolving our platform." Slack's content design team has written about this directly: avoid jargon like "deprecating" or euphemisms like "sunsetting" in customer-facing copy. It delays understanding and wastes their time. "On October 1st, the v1 authentication endpoint will stop working. You must migrate to v2 before then" is the right register.

On the "why": frame it around necessity. If the change is driven by a security requirement, say so. If it is a compliance obligation, name it. Stripe's approach to API stability, documented by Will Larson, is instructive here: Stripe treats API deprecation as an exception requiring CEO approval, and the one documented exception was TLS 1.2 deprecation for PCI compliance. The lesson is not that you need CEO approval; it is that the bar for a breaking change should be high enough that you can explain it clearly. If you cannot explain why the change is necessary in two sentences, the rationale is not ready.

On channel strategy: a single email is not a communication plan. The announcement should live in the release notes, the developer portal, the support knowledge base, and in-app notifications. The goal is that no matter where a customer looks, the information is there. Slack's practice of starting with an in-app banner 60 days before a deprecation, then escalating to a full-stop dialog at the deadline, is a useful model for sequencing. The banner is short and points to the documentation. The documentation is where the detail lives.

The Migration Window

The migration window is where most communication plans fall apart. The announcement goes out, customers acknowledge it, and then nothing happens until two weeks before the deadline when everyone panics.

The fix is a structured cadence. Send a reminder at the halfway point. Send another 30 days out. Send a final warning 7 days out. Each reminder should include updated usage data if you have it: "You still have active traffic on the deprecated endpoint." That specificity matters. Generic reminders get ignored. Personalized ones do not.

For customers who have not migrated as the deadline approaches, escalate. If significant traffic is still hitting the deprecated endpoint in the final weeks, reach out directly. Do not wait for them to come to you. Carnegie Mellon researchers studying breaking changes across software ecosystems found that the costs of change are often distributed unevenly, with some consumers facing significantly more rework than others depending on how deeply they have integrated. The customers with the most rework ahead of them are the least likely to respond to a generic email.

Define your escalation protocol before the announcement goes out. Who owns the conversation when a major customer threatens to leave? What flexibility exists on the deprecation date? If the date is a hard line for compliance reasons, the account team needs to know that before they make promises they cannot keep.

The Part That Breaks Trust After the Announcement

Here is where things go wrong even when the announcement was good.

Teams that rely on manual documentation updates often ship the breaking change before all the supporting materials are ready, or they mark deprecations inconsistently across different parts of the docs. The API reference says one thing, the changelog says another, and the support article is three versions out of date. Research on deprecated API usage in open-source Java projects found that the deprecated-removed protocol is often not followed, with documentation inconsistencies creating downstream confusion for developers trying to migrate. The same pattern shows up in commercial APIs.

This is where trust actually breaks down. When a developer tries to follow your migration guide and it does not match the new API behavior, they stop trusting your documentation. And when they stop trusting your documentation, they start opening support tickets, posting in forums, and telling other developers not to rely on your platform.

The Software Engineering at Google book describes this dynamic directly: good deprecation requires "documentation, plenty of signposts, and teams of experts helping with the deprecation and migration process." The signposts only work if they are consistent. A signpost that points in two directions is worse than no signpost at all.

The operational challenge is ensuring every downstream artifact reflects the breaking change before the announcement goes out, and stays consistent through the migration window. That means release notes, API references, changelogs, and support articles all need to be updated, cross-checked, and kept in sync as the migration period progresses. Teams that generate and update documentation directly from engineering workflows, rather than relying on manual updates after the fact, catch breaking changes earlier and communicate them consistently across every surface where a customer might look. Doc Holiday is built around this workflow: it generates release notes and API references directly from code commits, and provides the structure for a technical writer or support lead to validate that all breaking changes are clearly marked and consistently explained across every customer touchpoint before the announcement goes out.

Customers can handle breaking changes. What they cannot handle is being surprised, abandoned during migration, or given incomplete information. The communication plan matters more than the change itself.