Surviving Platform API Deprecations Without Breaking Your Product

Every team building on social APIs eventually loses an endpoint. It is not a risk to avoid, it is a recurring maintenance cost to plan for, and the difference between a bad week and a bad quarter is almost entirely about how the code was structured beforehand.

The good news is that platforms are reasonably predictable about this. There is a published record of what they removed, when they announced it, and how long they gave. The bad news is that the notice is shorter than people assume and the clock often starts before anyone notices.

Here is the actual history, what the notice periods were, and how to build so the next one costs you a sprint.

What has actually happened?

Basic Display is the one people remember, because it took thousands of embeds and creator tools offline in a morning. It had launched in 2019, so it ran for 5 years and died in 90 days. We wrote up the migration in the Basic Display deprecation guide.

The more useful rows are 3 and 4, because they show the repeatable pattern rather than the headline event.

What is the 2 stage pattern?

Meta publishes most deprecations against a specific version first, then applies them everywhere a few months later. Both dates appear in the changelog, and teams usually read the first one.

• Stage 1. The change lands on the newest version. If you are pinned to an older version, nothing happens and you feel fine.
• Stage 2. The change applies to all remaining versions, including unversioned calls, on a stated date. This is usually about 3 months later, and it is the date that actually breaks you.

The Instagram audience insights retirement is a clean example. It arrived with v18.0 in September 2023 and applied to all versions on 11 December 2023. A team pinned to v17 had roughly 3 months, not the 2 years they thought their pin bought them. That change is also why the demographic endpoints work the way they do now, which we cover in the audience demographics post.

Before planning any migration, check which fields you actually use. Per-platform coverage is public. See the coverage list

Does pinning a version protect you?

Partly, and less than it feels. Meta ships a Graph API version roughly quarterly and supports each one for about 2 years, so a pin buys you a known expiry date rather than safety.

3 things a pin does not protect you from:

1. All-version changes. When a changelog says a deprecation applies to all remaining versions on a date, your pin is irrelevant.
2. The 2 year wall. Your pinned version has an "available until" date published alongside it. Version 18.0 was released in September 2023 and listed as available until January 2026.
3. New requirements. Verification rules, scope reclassifications and account type requirements can arrive outside the version system entirely.

What a pin genuinely gives you is a date you can plan against. Put the "available until" date for every platform in a shared calendar and bump the version ahead of it rather than waiting for the 4xx responses.

Unversioned calls are the worst position, because they resolve to whatever your app dashboard says, and they move when the platform decides rather than when you do.

What if there is no replacement?

This is the case teams never plan for, and it happens. Meta's v26.0 changelog retires the Commerce Order Management API across 47 endpoints and states plainly that no replacement API is available. The same note appears against the Instagram Explore Feed placement.

So the planning question is not only "how do we migrate" but "what do we tell customers if this capability simply stops existing". That is a product conversation, not an engineering one, and it goes much better when it starts in the notice period rather than the week after.

LinkedIn shows a slower version of the same thing. Its Sales Navigator partner programme stopped accepting new partners, so the capability is still there and the door is shut. Details in the LinkedIn scope reference.

How should the code be structured?

So that a platform change touches 1 file. This is what a connection layer does for you, and it is worth building even if you keep it in house.

# Keep platform shapes out of your product code.
# Your app asks for "followers". The adapter knows that means
# edge_followed_by.count on one platform and subscriberCount
# (as a STRING) on another.

class InstagramAdapter:
    API_VERSION = "v23.0"          # one constant, one place
    SUNSET      = "2027-06-01"     # from the changelog. Alert on it.

    FIELD_MAP = {
        "followers": "followers_count",
        "handle":    "username",
        "bio":       "biography",
    }

    def profile(self, account):
        raw = self._get(f"/{self.API_VERSION}/{account}", self.FIELD_MAP)
        return normalise(raw, self.FIELD_MAP)

# Benefits when a deprecation lands:
#   - version bump is 1 line
#   - a renamed field is 1 line in FIELD_MAP
#   - a removed field fails in 1 place, not 40
#   - SUNSET is a value you can monitor rather than a date in a doc

The field map is doing more work than it looks. The same concept has a different name and sometimes a different type on every platform, as we worked through in social data API coverage. Keeping that mapping in 1 place is what makes a rename a 1 line change instead of a search across the codebase.

What should the process look like?

1. Put changelog review in someone's calendar. Monthly for Meta and LinkedIn, since LinkedIn ships a version every month. Quarterly is enough for the rest.
2. Track a sunset date per platform as a value in your code, and alert when it is within 90 days, the same way you would a token expiry.
3. Log which fields you actually use. Most teams request more than they render, and you cannot assess a deprecation without knowing what you depend on.
4. Keep a fallback path for display. If a field disappears, showing a clear empty state beats showing a stale value or an error.
5. Budget for it. 1 or 2 migrations a year per platform is normal. A roadmap with no maintenance allocation will absorb it by cutting something else.

Is this a reason to avoid APIs?

No, and it is worth being clear about the comparison because it is the usual counter-argument for scraping.

API risk is announced and dated. You get a changelog entry, a notice period and usually a migration path. Scraping risk is silent and continuous, arriving whenever a site changes its markup, with no notice and often no error, because a page that returns a 200 can still be garbage. We put real numbers on both in the API versus scraping cost comparison.

Neither is risk free. The question is whether your team is better set up to absorb a known deadline or a stream of unannounced breakages, and most product teams handle the deadline better.

Summary

Deprecations are a maintenance cost, not an emergency, provided you read the changelog before the calls start failing. The record shows roughly 90 days of notice on a full shutdown, and about 3 months between a change landing on the newest version and applying to every version.

Pinning a version gives you a published expiry date rather than protection, so track that date and bump ahead of it. Keep platform specifics behind an adapter so a rename is 1 line. And plan for the case where the capability simply ends, because the changelogs do sometimes say that no replacement is coming.

Want 1 integration that absorbs platform changes instead of passing them to you? Get a demo