A Support Workflow for Shipping Breaking API Changes

You handle a breaking API change best by doing most of the support work before you ship it. Find out which customers are affected. Write the migration guide and your common replies before the first announcement. Signal the deprecation in the API responses as well as in email. Then plan the cutover day the way you would plan a deploy.

The workflow below has seven steps. It's written for solo developers and small teams who write the code and also answer the tickets.

What counts as a breaking change

Many support problems start because the person shipping the change didn't think it was breaking. Two public references give useful definitions.

GitHub's REST API versioning docs list these as breaking:

• removing an operation
• removing or renaming a parameter or response field
• adding a required parameter, or making an optional parameter required
• changing the type of a parameter or response field
• removing enum values
• adding a new validation rule to an existing parameter
• changing authentication or authorization requirements

Adding things, such as new endpoints, optional parameters or response fields, is not breaking under that policy.

Google's AIP-180 on backwards compatibility goes further. It covers "semantic" compatibility: old code should keep getting what reasonable developers would expect. Under that rule, these also count as breaking:

• changing a static default value
• changing the format of an output field (its example is switching an IP address field from IPv4 to IPv6)
• starting to include fields that used to be left out when they held default values

It also warns against changing visible behavior that client code probably relies on, even if you never documented it.

Why this matters for support: if your change fits any of these descriptions, plan the support work for it. A change that is breaking in practice will produce tickets, whatever your changelog calls it.

Step 1: Decide whether it has to break

The cheapest breaking change for support is the one you don't ship. AIP-180 treats a rename as "remove and add." You may add the new name, but you should keep the old one. You can often do the same thing:

• add the new field and keep filling in the old one
• add a new endpoint instead of changing the existing one
• put the new behavior behind an opt-in parameter or version header

If you follow Semantic Versioning, a breaking change requires a new major version. The spec also asks for at least one minor release that marks the feature as deprecated before you remove it, so users have time to move.

Analysis: keeping two paths alive costs engineering time. A forced migration costs support time for every affected customer. For a small team, compare both costs before you decide.

Step 2: Build a list of affected customers

Before you announce anything, find out who actually calls the endpoint, field or behavior that is changing. Useful sources:

• request logs grouped by API key or account, filtered to the affected endpoint or parameter
• the API version each account sends, if you version by header
• webhook endpoint settings, if the payload shape is changing
• SDK version strings in User-Agent headers, if your SDKs send them

The result should be a short list, not a guess. That list lets you email affected customers directly instead of every customer. It also tells you who to follow up with later.

Large providers make this data visible to their own users. For example, Stripe's upgrade guide tells developers to set the API version explicitly in code and to check which versions their integration uses in Workbench. You don't need a dashboard that polished. A saved log query you can run again before each reminder is enough.

Step 3: Write the support materials before you announce

When customers ask questions, the answers should already exist. Prepare these first:

1. A migration guide. Show the old request and response next to the new ones, with the exact field names and the dates. Explain why the change is happening in one or two plain sentences.
2. A changelog entry that links to the guide.
3. Draft replies for the questions you expect. For example: "What do I need to change?", "Can I get more time?", "I upgraded and now get errors" and "Does this affect my webhooks?"
4. A clear error for after the cutover. The response for removed functionality should tell the developer what happened and link to the guide. GitHub returns 410 Gone for requests to a version that is no longer supported.

Breaking changes often show up as integration questions, such as SDK mismatches, webhook payload differences and auth errors. Our checklist for product integration questions helps you collect the right details on the first reply.

If you are reworking your saved replies for this change, keep them sounding like you. See how to ship support updates without breaking your voice.

Step 4: Announce the change in email and in the API

Email gets missed. Developers read logs, and API clients can read headers. Use both.

Documented standards you can use:

• The Deprecation header (RFC 9745, a Standards Track RFC published March 2025). It tells clients a resource is deprecated, or will be on a given date. It doesn't change how the resource behaves. The value is a structured date in the form @ plus a Unix timestamp.
• The Sunset header (RFC 8594, Informational, May 2019). It tells clients when a resource will probably stop responding. The value is an HTTP-date. RFC 9745 says the Sunset date must not be earlier than the Deprecation date.
• Link relations. RFC 9745 defines rel="deprecation" and RFC 8594 defines rel="sunset". Both point to human-readable documentation, such as your migration guide. RFC 9745 notes that clients shouldn't assume the link is secure unless it's served over HTTPS.

A hypothetical response for an endpoint deprecated on November 1, 2026 and retired on February 1, 2027:

Deprecation: @1793491200
Sunset: Mon, 01 Feb 2027 00:00:00 GMT
Link: <https://example.com/docs/migrate-v2>; rel="deprecation"; type="text/html"

Both RFCs describe these headers as hints, so they don't replace direct communication. GitHub is one real example: as a version nears the end of support, its API responses include Deprecation and Sunset headers.

The announcement email to affected customers should say:

• what is changing, in one sentence
• whether this customer is affected, and how you know (for example, "your account called /v1/orders with status_code in the last 30 days")
• the deprecation date and the removal date
• a link to the migration guide
• how to reply if they need help or more time

Step 5: Pick a realistic timeline and send reminders

How long to give customers is a judgment call. Here are some published reference points:

• GitHub supports the previous REST API version for at least 24 months after a new one is released.
• Stripe releases monthly API versions with no breaking changes. Breaking changes come only in major releases, twice a year, as described in its versioning docs.

A small team probably can't maintain two versions for two years, and that's fine. What matters is giving customers a timeline they can plan around and then keeping to it.

Hypothetical schedule for a small SaaS:

Before each reminder, run the query from Step 2 again. Customers who have already migrated should stop getting emails. Customers who haven't moved after two reminders usually need a personal email rather than another broadcast.

Step 6: Treat removal day like a deploy

Expect more tickets on the day the old behavior stops working, and plan time for them:

• Choose a day and time when you can watch the inbox. Avoid Friday evenings and your own holidays.
• Clear the queue the day before. Our guide on building a support buffer before shipping shows how.
• Decide your rollback rule in advance. For example, a big customer you missed in Step 2 might get a short, documented extension.
• Keep the migration guide, the draft replies and the log query open so you aren't switching between tools all afternoon. Running support between deploys without losing context covers this in more detail.

Make the first reply to a broken integration specific. Name the change, the date and the exact field or endpoint, and link to the section of the guide that fixes their error. A general "please see our changelog" reply usually leads to a second ticket.

Step 7: Close the loop

When things have calmed down:

• Tag every ticket that mentions the change, and note which questions came up most often.
• Add those answers to the migration guide. The next person may find the answer there instead of emailing you.
• Write down what you'd change next time, such as an earlier first email, a clearer error message or a better log query.

Opinion: this short review is the most valuable step, and it's the one people skip most often. Your second breaking change will be much easier if you keep notes from the first.

Where AI drafting can help, and where it can't

A breaking change produces many similar questions in a short time, so drafted replies can save time here. SupportMe, for example, is built to draft email replies in your writing style from your knowledge base. Nothing sends without your approval, and it learns from the edits you make before sending.

For this kind of work, the human review matters more than usual. Dates, version numbers and field names have to be exactly right. A reply that's almost right about a removal date is worse than no reply. Read every draft against the migration guide before you send it. If you want to see how much you changed, comparing the draft with the sent reply shows you quickly.

Conclusion

You make a breaking API change easier to support by doing the work in a set order:

1. Make sure the change really has to break.
2. Find the affected customers in your logs.
3. Write the guide and replies before announcing.
4. Announce in email and in the API, using the standard Deprecation and Sunset headers.
5. Send reminders only to customers who haven't migrated.
6. Plan removal day like a deploy.
7. Add what you learn to the guide.

None of this needs a large team. It needs a clear timeline, a short list of affected customers and answers written before the questions arrive.

References

• GitHub Docs: API versions
• Google AIP-180: Backwards compatibility
• RFC 9745: The Deprecation HTTP Response Header Field
• RFC 8594: The Sunset HTTP Header Field
• Semantic Versioning 2.0.0
• Stripe Docs: Versioning
• Stripe Docs: Upgrade your integration