What counts as a breaking change?
The test is simple: if a customer does nothing and something they rely on stops working, the change is breaking. It does not matter whether the change is large or small in code. A renamed field in an API response can break more customers than a full redesign.
Breaking changes show up in several places:
- APIs and webhooks: removed endpoints, renamed parameters, changed response shapes, stricter validation, or new authentication requirements.
- Platform support: dropping an older operating system, browser, database version, or SDK.
- Behavior and defaults: changing what a setting does, how data is sorted, or how a limit is enforced.
- Data and exports: new file formats, changed column names, or altered date and number formats.
- Pricing and packaging: moving a feature to a higher plan or retiring a plan entirely.
In semantic versioning, a breaking change is what forces a new major version. The version number is a signal to developers that they must read the notes before upgrading. Products without version numbers still ship breaking changes; they just lack the built-in warning.
Why breaking changes matter for product and customer success teams
A breaking change moves work from your team to your customers. Every affected account has to notice the change, understand it, schedule the fix, and test it. If they miss the announcement, they find out when something fails in production.
The consequences are concrete:
- Support load spikes. Tickets arrive from customers who did not see the notice, often all at once on the day the change ships.
- Trust erodes. A customer who was surprised once will treat every future product update as a risk and delay adoption.
- Renewals get harder. Enterprise buyers ask about change management during security and procurement reviews. A history of unannounced breaks is a mark against you.
- Integrations go stale. Partners and agencies who built on your API may not have anyone watching for changes. A silent break can disable their product too.
Handled well, a breaking change is a normal part of release management. Handled badly, it becomes an incident that needs incident communication after the fact. Read how versioning fits into your changelog for the mechanics.
Examples of breaking changes
These patterns appear across most SaaS products:
- An API version is retired. A payments or messaging platform announces that an older API version will stop responding on a fixed date. Customers must migrate their code to the current version or their requests fail.
- A language drops backward compatibility. The move from Python 2 to Python 3 changed core syntax, so existing scripts would not run without edits. The community needed years and repeated reminders to complete the transition.
- A required credential is introduced. A mapping or analytics service starts requiring an API key on every request. Embeds that worked for years show an error until an owner adds a key.
- A webhook payload changes shape. A field moves from a string to an object. Every consumer that parses the old shape silently receives bad data or throws an exception.
In each case the fix is small for any single customer but expensive across the whole base. That is why the announcement matters as much as the engineering.
How to announce a breaking change
Treat the announcement as part of the release, not an afterthought. A useful sequence:
- Decide if it must break. Look for a compatible path first: keep the old field alongside the new one, add a version flag, or ship a migration script. Avoid the break when the cost is reasonable.
- Publish a deprecation notice early. State what is changing, why, the exact date, and what customers need to do. Give a window long enough for enterprise release cycles.
- Identify who is affected. Use usage data to find accounts that call the endpoint or rely on the setting. Message them directly instead of hoping they read a general post.
- Repeat across channels. One post is not enough. Combine the changelog, an email, an in-app notice, and a Slack or developer newsletter mention. Remind again as the date approaches.
- Write a migration guide. Show before and after examples. Link it from every reminder.
- Mark it clearly on release day. Put a visible label such as Breaking at the top of the release notes so nobody has to hunt for it. See the Keep a Changelog format for a convention that handles this.
- Watch after shipping. Track support tickets, error rates, and feedback for the next few days and be ready to extend the deadline if adoption lags.
Breaking change vs. deprecation vs. regular product update
Teams often blur three related ideas:
- A breaking change is the event: the moment old behavior stops working.
- A deprecation is the warning period before that event. The old behavior still works but is marked for removal. Every breaking change should be preceded by a deprecation; not every deprecation has to end in a break.
- A regular product update adds or improves something without removing what customers depend on. It belongs in release notes but needs no migration.
Common mistakes:
- Burying the break. Listing a removed endpoint as the fourth bullet under "Improvements" guarantees that customers miss it.
- Announcing once. The people who need the notice most are the ones who rarely read your changelog. Plan for repetition.
- Skipping the why. Customers accept change when they understand the reason. A single sentence about security, performance, or simplification goes a long way.
- Confusing a bug fix with a break. If customers built on buggy behavior, fixing it can still break them. Announce it the same way.
- No owner on the customer side. Notify every user on an account, not only the person who signed up. Learn more in how often to publish product updates.
How AnnounceKit handles breaking change
AnnounceKit gives you one place to publish the notice and several ways to make sure it is seen. The changelog page lives on your own domain, so developers can bookmark and search it. More than ten in-app widget display modes let you show a persistent banner or modal to affected users inside your product. Segmentation targets the notice to accounts that actually use the endpoint or plan being changed, and email digests plus Slack delivery cover the people who are not logged in. AI post generation helps draft the migration guide from your notes, and the official MCP server lets AI agents read your changelog so customer tooling can pick up the change automatically. Pricing is flat per project from $79/month with a 15-day free trial.