A Playbook for Sunsetting an API Without Breaking Customers

Instrument the deprecated version, not just the new one, so you have real call volume and, ideally, real caller identity before you set a shutdown date. A version with near-zero traffic can move fast; a version still handling meaningful volume from a small number of identifiable accounts needs direct outreach to those accounts specifically, not just a changelog entry that assumes everyone reads it.

• Announce with a concrete date, not eventually, and add a deprecation header to every response from the old version so it shows up in server logs on the caller's side too, not just yours.
• Reach out directly to any account still generating meaningful traffic, ideally through the same channel they'd expect a real incident notification through, not just an email that might land in a bulk folder.
• Add a warning period where the old version still works but returns a deprecation notice in every response body, giving integrations that parse responses programmatically a chance to notice even if a human never reads the changelog.
• Shut down only after real traffic on the old version has dropped to the small number of accounts you've already contacted directly, not on the calendar date alone if traffic tells a different story.

A deprecated endpoint that still works exactly as before doesn't just cost you nothing to leave alive, it costs you invisibly: every dependency you don't update, every security patch you have to apply twice, every engineer who has to remember which version is current when debugging.

The riskiest kind, though, is a deprecated internal-facing endpoint from an old integration nobody remembers building, still reachable from the internet with no monitoring on it at all, since a target nobody's watching is a target nobody notices being probed.

Confirm the endpoint's real traffic, not the traffic you expect, since a batch job that only runs quarterly can look dead for months and then break loudly the one time it fires. Confirm you've reached every account still generating traffic through a channel you know they'll see. Confirm the deprecation headers and warning-period notices have actually been live long enough for a reasonable integration cycle, not just technically present for a day before shutdown.

Say traffic on a deprecated API version has dropped to a small handful of remaining callers, and every one of them has been contacted directly except a single account that's been quiet since the outreach email went out. Shutting down on schedule anyway, on the theory that one unresponsive account isn't worth delaying for, is how you find out that account is a partner whose integration processes a meaningful share of their own customer orders through your API, and they simply hadn't seen the email yet.

Before a final shutdown, escalate outreach to any remaining account through more than one channel, a support ticket, a phone call for a high-value account, not just a repeat of the same email that already went unanswered.

A deprecation that's painful once is usually a sign the API's versioning strategy makes every deprecation painful. Explicit version numbers in the URL or a header, rather than a single evolving endpoint, let you run two versions side by side indefinitely if needed, which turns a hard cutover into a gradual migration. Teams that treat every API change as a breaking change to the one true endpoint end up either afraid to deprecate anything, or forced into exactly the rushed, under-communicated shutdown this playbook is trying to avoid.