API deprecation: shut down v2 without stranding your customers

Every API team that has shut down a version knows the curve. A quick drop in v2 traffic after the announcement, then a long, flat tail of customers who never move. Shutdown day arrives, support gets the calls, and the date moves.

Why the tail doesn't move

It isn't that customers didn't read the email. They did. They added a ticket. The ticket competes with their own roadmap, and "rewrite working code to call a newer endpoint" loses every sprint planning.

The cost of migrating sits in the customer's codebase, and nothing you send changes that.

What actually helps, in order of effort

1. A migration guide with exact before and after code for each SDK language. Not a list of changed fields, actual code.
2. Codemods: scripts that rewrite the common call patterns. Customers still have to find, run and review them.
3. Response headers and SDK warnings (Deprecation, Sunset, a log line on every v2 call), so the developer sees it, not just the account owner.
4. A migration in their repository: a pull request with their calls rewritten and their tests run. Merging is a review, not a project.

Each step moves more of the tail, because each one moves more of the work off the customer.

Doing step 4 at scale

That's the provider program in Versyka:

• Share your install page. You get versyka.com/install/your-company to put in your changelog, upgrade emails and docs. Customers who install from it opt in; nothing touches a repository without them.
• Publish the change once. Paste the migration guide you already write; it becomes a precise rewrite rule.
• Customers get tested pull requests. Every opted-in repository that uses your SDK gets one, with the customer's own tests run. It's free for them: you sponsor it, and nothing merges without their review.
• Watch adoption. The portal shows pull requests opened, merged and repositories not affected, per change. Counts only: customer names stay private.

Plans start at $1,500 a month on an annual contract.

Even if you never use a tool for it

Put the before and after code in your guide. Send the deprecation signal through the SDK, not only the inbox. And count the tail by repository, not by account. That last number tells you what shutdown day will look like.

If you've run a version shutdown, I'd like to know what moved your long tail. Comments are open.