API Deprecation Plan Template for Product Teams

Minimum 6 months for external APIs with significant consumer bases. 12 months for APIs with enterprise consumers who have long release cycles. Internal APIs can move faster (3 months) if you control all consumers. The key constraint is your slowest-moving consumer's release cycle, not your preference. Check your [SLA](/glossary/service-level-agreement-sla) for any contractual obligations.

No. Charging for the old version creates perverse incentives: consumers pay to avoid migrating, which delays your ability to shut down the old infrastructure. Instead, make the new version strictly better (new features, better performance, improved DX) so migration is attractive rather than punitive.

410 Gone. This tells consumers (and their monitoring systems) that the resource existed but has been permanently removed. Include a response body with the migration guide URL and the new API version's base URL. Do not use 404 (implies the resource never existed) or 301 (implies automatic redirect, which will break integrations).

Start with direct outreach to understand their blockers. Common reasons: they do not know about the deprecation (communication failure), the migration guide does not cover their use case (documentation gap), or they lack engineering bandwidth (timeline issue). For the first two, fix the root cause. For bandwidth issues, offer a time-limited extension (max 90 days) with a written commitment to migrate. Do not extend indefinitely. Track these extensions in the consumer impact table.

Only if the migration is genuinely complex and affects many consumers. A compatibility layer (v1 requests translated to v2 internally) buys time but adds maintenance cost and delays full migration. If you build one, set a hard sunset date for the shim itself. The [RICE Calculator](/tools/rice-calculator) can help you evaluate whether the engineering investment in a shim is justified based on the number of affected consumers. ---