What to Do When a Third-Party API Is Being Retired
Treat a third-party API retirement as a dependency change with a deadline: identify every affected workflow, choose a supported replacement, and test the move before switching. Your third-party API deprecation migration checklist should cover version support, behaviour changes, historical data, cutover, rollback limits, and customer communication. Judge completion by whether customers can finish their work and access their records.
What exactly is being retired?
Start with the provider's official retirement notice and migration documentation. Record what is ending: an endpoint, an API version, an authentication method, a client library, or the entire service.
Separate the end of support from the end of availability. Ask the provider to confirm whether requests will stop working, support will end, or access will become restricted. Do not assume those events happen together.
Check the scope for your account, subscription, region, and current version. If the announcement leaves anything unclear, get a written answer.
Choose an earlier completion point that leaves room for testing and recovery. Treat any extension as confirmed only when the provider has explicitly granted it for your account.
Which workflows depend on the API?
Inventory business workflows before estimating code changes. For each dependency, identify the customer action, the background work it triggers, and the result someone expects.
Include scheduled jobs, incoming event notifications, reports, imports, exports, and support tools. Trace incomplete work too: queued requests, failed jobs awaiting retry, and records that still need an update.
Use a table like this to make the scope reviewable:
| Workflow | Dependency to check | Proof required |
|---|---|---|
| Create a booking | Availability lookup and reservation | One confirmed booking with the correct details |
| Update a record | External identifier and update request | The intended record changes once |
| Receive a status change | Event subscription and processing | The status reaches the correct customer record |
| Download a report | Historical records and pagination | Required records and totals reconcile |
| Recover a failed action | Retry rules and duplicate prevention | Recovery finishes without repeating the action |
Give each workflow a named owner and a consequence if it stops. Prioritise paths that create commitments, change records, or block customers from completing essential work.
For broader maintenance planning, see technical debt explained for founders.
Is the replacement supported for your needs?
Compare a newer version from the same provider with another service only where both are realistic choices. Require evidence that the replacement supports your essential workflows.
Check supported versions, maintenance status, authentication requirements, account access, and any announced retirement policy. Confirm which client-library versions work with the chosen API.
Review commercial and operating constraints as well:
- Are required features included in your subscription?
- What usage limits apply to normal traffic and the migration itself?
- Can you export your records if you leave later?
- What support is available during the move?
- Are the data handling terms acceptable for the information you send?
Avoid committing based on a successful demonstration of one request. Approve the replacement against the complete workflow inventory.
Which behaviour changes need testing?
Build a comparison of the old and new interfaces from their documentation, then verify it with representative requests. Record differences in meaning as well as differences in field names.
Check required fields, defaults, empty values, identifiers, units, time zones, rounding, sorting, pagination, and error responses. For incoming events, examine delivery order, duplicate handling, retry expectations, and how authenticity is verified.
Test uncertain outcomes deliberately. If a request times out after submission, how will your application determine whether the action happened? Require a recovery path that checks the result before repeating an action with consequences.
Use realistic cases: an older record, an incomplete record, a large result set, an expired credential, and an interrupted request. Compare the customer-visible result with an agreed expectation.
The acceptance criteria should describe completed work, such as “the customer sees the confirmed reservation”, rather than “the endpoint returns success”. See software testing and quality assurance practices for related planning.
What happens to historical data?
Decide which records must move, which can remain in a readable archive, and which should be deleted under your retention policy. Check contractual and applicable legal requirements before choosing.
Include attachments, relationships between records, status history, timestamps, and references used by reports or customer links. If identifiers change, keep a mapping that lets your application find the corresponding record.
Practise the export and import before relying on them. Compare record counts, required fields, relationships, and representative reports. Define how you will detect missing, duplicated, or rejected records.
Choose a method for changes made during the transfer: briefly pause writes, copy subsequent changes, or use another tested approach. Reconcile the final result before declaring the transfer complete.
Confirm archive access independently. A saved export is useful only if authorised people can open it and retrieve the information they need.
How should cutover and rollback work?
Write a cutover sequence with entry conditions, a responsible person, and a stop condition for each step.
Before starting, require accepted workflow tests, reconciled data, working credentials, and a clear way to observe completed actions and failures. Where practical, switch a limited group first and expand only after checking the results.
Avoid sending the same live action to both providers unless you have designed and tested how to prevent duplicate effects. Use copied requests for comparison only where doing so is permitted and cannot create unintended actions.
Define rollback boundaries explicitly. Ask:
- Will the old API still accept requests?
- Can it read records created through the replacement?
- Can new identifiers and changed data be translated back?
- Which external actions would require correction?
- How will records changed during the switch be reconciled?
Do not promise rollback after retirement unless continued access is confirmed. Prepare a fallback for that point: pause an affected feature, preserve pending work, or use an approved manual route.
Practise the fallback and the return to normal service. A switch back is incomplete until both systems' records have been reconciled.
What should customers be told?
Tell customers what affects their work: changed behaviour, required action, expected interruption, and available help. Explain whether existing records, links, or integrations need attention.
Keep technical replacement details out of general notices unless customers must act on them. Customers who maintain their own integrations need separate instructions covering compatibility, required changes, testing, and how completion will be confirmed.
Prepare messages for the planned move, an unexpected interruption, and completion. Publish the completion message only after checking customer workflows and data access.
If customers need to reconnect an account or grant permissions again, explain the steps and where they can get help.
Which common mistakes should you avoid?
Treating the change as a URL replacement. Review business behaviour and data meaning before estimating the work.
Testing only new records. Include historical records, pending actions, and partially completed workflows.
Confusing successful requests with successful migration. Verify outcomes, record relationships, and customer access.
Assuming rollback remains available. Confirm the old service's availability and test what happens to new data.
Leaving the move until the retirement point. Set aside time to resolve failed transfers and unexpected differences.
Combining unrelated improvements with the migration. Keep the change focused enough to identify the cause when an acceptance check fails.
Before closing the work, confirm:
- Every affected workflow passes its acceptance checks.
- Required historical data is reconciled and accessible.
- Pending work is completed or safely preserved.
- Cutover and fallback instructions have been exercised.
- Customer actions and support guidance are clear.
- Obsolete access is removed once recovery no longer requires it.
What are the frequently asked questions?
Does deprecation mean the API has already stopped working?
Use the provider's notice to establish that. Ask separately about continued availability, maintenance, support, and the final shutdown point.
Should we upgrade or change providers?
Compare both against essential workflows, data portability, support, cost, and migration effort. Choose the option you can validate within the available window.
Can we keep an old client library?
Check its documented compatibility and support status. Test it against the replacement rather than treating a working installation as proof of compatibility.
When is the migration complete?
Close it after customer workflows pass, required data is reconciled, pending actions are resolved, and the agreed observation period ends without unresolved failures.
*Need help assessing an API retirement and planning the replacement? Start a conversation →*