An API version used by about 3,000 integrators must be retired. Usage is long-tailed - 40 integrators account for 80% of calls and the remainder are small, some with no active developer. Give the sequence and say where it can go wrong.

The sequence

1. Measure before announcing. Per-integrator call volume, last-call timestamp, and which specific removed features each one uses. Most of the plan follows from the data: a deprecation is a per-integrator migration project, not one broadcast. Expect to find that a third of registered integrations have not called the API in a year.
2. Publish the new version and a written migration guide - field-by-field, with a worked before-and-after example. Nothing is announced until a migration path exists that someone has followed end to end.
3. Announce with a date, in channels that reach people. Email to the registered technical contact, a notice in the portal, release notes, and - the one that works - response headers on the old version itself: Deprecation and the Sunset header standardised in RFC 8594 (2019). A header reaches the integration even when the registered contact has left the company.
4. Work the top 40 by hand. A named person, a meeting, a test environment, and a date. These are most of your traffic and most of your revenue risk, and they migrate because someone asked them to.
5. Make the remainder self-serve. A migration guide, an automated compatibility check they can run, and a dashboard showing their own usage of the removed features.
6. Brownouts before the sunset. Return errors for the old version for a few minutes at announced times - rising from minutes to hours as the date approaches. This is the only mechanism that reliably finds the integrations whose owners are not reading email, because it generates an alert on their side.
7. Sunset in stages: lowest-volume cohort first, then by increasing volume, with a published schedule and a documented rollback for each stage.
8. Keep a break-glass path - a short, logged extension for a named integrator with a date - because something will be genuinely stuck and the alternative is an unplanned reversal.

Where it goes wrong

• The registered contact is stale. For small integrators the email address belongs to someone who left. This is why in-band signalling matters: headers and brownouts reach the system, not the inbox.
• A long tail that never migrates, and the decision to break them has no clear owner. Decide in advance - commercially, not technically - what call volume or contract value earns an extension, and apply it consistently.
• Mystery traffic. Calls with no identifiable integrator, often an internal service nobody mapped. Finding these is what step 1 is for.
• An ambiguous timetable. "Deprecated" without a removal date means nothing happens. The announcement must contain the date on which calls stop working.
• Your own systems still calling the old version, discovered during the final stage.

The point of no return

Decommissioning the old version's code path. Before that, every stage is reversible by re-enabling it. Keep it deployable but disabled for one release cycle after sunset - it is cheap, and it converts "we must do an emergency release" into "we flip a flag".

How long it really takes

For 3,000 integrators with a long tail, 12 to 18 months from announcement to sunset is the realistic range, and the time is dominated by negotiation with the top cohort and by waiting out the tail, not by engineering. A 6-month plan is a plan to break small integrators and then reverse under pressure.

When this is the wrong approach

If the old version carries a security defect, this timetable is unaffordable and the calculus changes: mitigate in place if you possibly can, and if you cannot, a short forced migration with direct outreach is the correct answer - the integrators affected would rather be broken than breached. Say which of the two situations you are in before choosing the plan, because the two plans are incompatible.