Designing API Change Notifications: How to Tell Customers Before You Break Them

Every API team has a changelog. Most changelogs are written for the team itself: a chronological record of what shipped, in the team's preferred level of detail. Customers can read them, but most do not, and the ones who do read them often discover changes only after their integration has broken. The asymmetry is severe: the API team knows about every change in advance, and customers discover changes at the time of breakage.

The patterns that close this gap are not about writing more or better changelogs. They are about routing changes to channels matched to their impact, and giving customers ways to subscribe to the level of detail they care about. The discipline is mostly editorial, with a small technical infrastructure component for the most important cases.

The four-tier classification

Every API change falls into one of four impact tiers, and each tier deserves a different notification approach.

Tier 1 is breaking changes: removing endpoints, changing response schemas, changing semantics of existing fields, tightening validation. These break working integrations and require customer action. They deserve the highest-impact notification: email to every account, deprecation warnings in API responses, dashboard banners, advance notice measured in months not weeks. Two years is the right window for most B2B SaaS; six months is the floor for anything except security-critical changes.

Tier 2 is potentially-breaking changes: new optional fields in requests, new optional fields in responses, new error codes, new endpoints, new query parameters. These do not break compliant clients but can break clients that make assumptions beyond the spec (clients that do strict schema validation on responses, clients that treat new error codes as unknown errors, clients that fail on fields they do not recognize). They deserve a structured changelog entry that customers can subscribe to via RSS or webhook, with one week to one month of advance notice depending on the change.

Tier 3 is non-breaking improvements: performance improvements, bug fixes that match documented behavior, error message improvements, new optional features. These deserve a changelog entry but no individual notification; customers who care will read the changelog.

Tier 4 is internal changes: infrastructure migrations, refactors that do not affect behavior, monitoring improvements, security improvements. These do not need a customer-facing entry at all. They deserve internal documentation, not changelog entries.

The deprecation pipeline for breaking changes

The two-year deprecation window is structured as four phases, each with a specific customer-facing signal.

Month 0 is announcement: changelog entry, blog post, email to all accounts using the affected endpoint or field, dashboard banner, response header (Deprecation: Sun, 18 May 2028 00:00:00 GMT) on every response from the affected endpoint. The header is the most under-used part: it is machine-readable, gets automatically logged by most HTTP clients, and is visible to customers who are not on the email list. The RFC 8594 Sunset header pairs naturally with Deprecation.

Month 6-18 is reminder: monthly email to accounts that are still using the affected endpoint, with usage data showing what is being called and from where. The personalization is high-leverage: most customers do not remember integrations they built two years ago, and an email saying "your integration at this IP is using this endpoint that will be removed" is much more actionable than a generic warning.

Month 22 is final warning: email to remaining accounts with two-week deadline, response body warning included in every response, support team primed to assist with migration.

Month 24 is removal: the endpoint returns 410 Gone (not 404) for the next 90 days, with a body explaining the change and linking to documentation. After 90 days, the URL becomes a regular 404.

The structured changelog for tier 2 changes

The changelog should be machine-readable in addition to human-readable. The standard pattern: a structured JSON or YAML file in the documentation repository, generated into HTML for the public changelog page and also exposed as RSS or webhook. Each entry has a date, a category (feature, deprecation, bug-fix, security), an impact level, the affected endpoints or fields, and a description.

The webhook-on-changelog pattern is the most under-used feature. Customers who care about API changes can subscribe to a webhook that fires on every changelog entry, with structured metadata about what changed. The implementation is straightforward: the changelog generation process posts to the same webhook delivery infrastructure used for normal product webhooks. Customers integrate with their own tooling: Slack notifications, JIRA tickets, automated test runs against the latest API.

The RSS alternative is the older and more universally-supported version of the same idea. Most teams should publish both: webhook for active integration, RSS for passive monitoring. The cost of both is small once the underlying changelog is structured.

The per-endpoint subscription pattern

A customer rarely cares about all API changes equally; they care about changes to the endpoints they actually use. The per-endpoint subscription pattern lets customers subscribe to changes affecting specific endpoints or feature areas. Implementation: an account-level setting that names the endpoints or tags of interest; the notification system filters changelog entries against the subscription list before sending email or webhook.

The subscription is populated automatically from usage data: the system knows which endpoints each account is calling and can pre-populate subscriptions based on actual usage. The customer can then opt out of subscriptions they do not want, but they start with coverage matched to their integration.

This pattern is more work than a flat changelog, and most APIs do not justify it. It earns its weight at scale: when the API surface is large enough that no customer uses more than a fraction of it, per-customer relevance filtering is the difference between change notifications customers act on and change notifications they ignore.

The header signals worth setting

Several HTTP response headers communicate API change information to clients, and most APIs underuse them.

Deprecation from the IETF draft: a date in HTTP-date format indicating when the endpoint or behavior was deprecated. Most HTTP clients log this header by default, so customer integrations that do nothing else still see it in their logs.

Sunset from RFC 8594: a date in HTTP-date format indicating when the endpoint will be removed. Pairs with Deprecation.

Link with rel="deprecation" or rel="sunset" pointing to documentation: a URL where the customer can read about the change. Pairs with the two above and makes them actionable.

API-Version or a custom header reporting the current and minimum supported API version: helps customers detect when they are using an old version.

None of these require client cooperation to be useful: they are visible to anyone who logs response headers, which is most modern HTTP clients. The cost to the API team is trivial; the benefit to customers is real.

The migration guide as core artifact

For tier 1 changes, the changelog entry is not enough; customers need a migration guide. The structure: what changed, why it changed, what the old behavior looked like in client code, what the new behavior looks like in client code, common migration patterns, what to test after migrating. The guide is referenced from the changelog entry and from the deprecation header link.

The most useful migration guides include diff-style before-and-after code snippets in the languages customers actually use (curl, Python, Node.js, Go covering 90 percent of API customers). The least useful are descriptions in prose that require the customer to infer what their code change should look like.

What not to do

Surprise removals: removing endpoints without the deprecation pipeline, even for endpoints you believe nobody is using. There is always at least one customer using it, and the customer support cost of a surprise breakage is higher than the maintenance cost of keeping it for two more years.

Silent behavior changes: changing what an endpoint does without changing the schema. These are the worst class of API changes because customer integrations do not break visibly; they start producing wrong results, which is harder to detect than an outright error and erodes trust more.

Burying breaking changes in feature announcements: a blog post titled "New X feature" that mentions in paragraph 12 that Y endpoint is being deprecated. Breaking changes deserve their own announcement; conflating them with features hides them from customers who are not paying close attention.

Inconsistent advance notice: deprecating one endpoint with two years' notice and another with six weeks' notice without an obvious distinguishing reason. The discipline of a consistent deprecation window is what makes customers trust that they have time to migrate.

Across our four products

Across DocuMint, CronPing, FlagBit, and WebhookVault, we use a unified changelog with category tags and per-product filtering. The deprecation header is set on every response from any endpoint that has been marked for removal, with sunset date populated from the changelog metadata. The two-year deprecation window has not yet been tested by an actual removal; the first one comes in mid-2026 and we expect to learn from it whether the discipline we have written down survives contact with reality.

The deeper observation is that API change notification is mostly a customer-experience problem disguised as a documentation problem. The technical infrastructure is modest: a structured changelog, response headers, a webhook hub. The expensive part is the discipline of classifying every change correctly and routing it to the right channel, every time, with no exceptions for "this one is small enough to not deserve the process." The exception is the change that breaks customers, and the cost of the broken integration is much higher than the cost of running the process for the change that did not actually need it.