Vendor API removed a response field: a six-step recovery playbook

A removed response field reaches you in one of three ways: a finding from a scheduled spec diff, a changelog entry someone forwards, or an error in production. The playbook below works for all three, in the same order. It uses one real removal as the running example: in its 2025-09-30.clover release, Stripe removed the auto-expanded coupon property from the Discount object and added a source property that carries it. If you only have the production error, do steps 1 and 2 against the vendor's current docs and spec, then continue.

1. Confirm the removal, and find out whether it reaches you yet

Check the vendor's published spec, not only the changelog. A spec diff names the two revisions it compared, which gives you a window. For the example, apibreak diff (made by the publisher of this site) between the stripe/openapi spec at 19 August 2025 (2025-08-27.basil) and 23 March 2026 (2026-03-25.dahlia) reports that line_items.data[].discounts[].discount.coupon no longer appears in the Checkout Session responses, with its 17 nested fields. Stripe's changelog entry Adds the Discount source property and removes the Discount coupon property confirms it and names the replacement.

Then ask the question that decides urgency: does the removal apply to the requests you send today? On a versioned API it usually does not, yet. GitHub's API versions page lists removing or renaming a response field as a breaking change and says breaking changes are released in a new API version, and Stripe puts breaking changes in the first version of a major release. A removal in a version you have not adopted is upgrade work, not an outage. Three caveats. Stripe webhook events use the version set on the endpoint (or the account default), not the version your code sends. A GitHub request without a version header uses the default version, 2022-11-28 today, and when a version closes down, such requests default, in GitHub's words, "to the next oldest supported version, not the closing down version." And GitHub reserves the right to release an unscheduled version, backport fixes, or "in rare cases, introduce a breaking change to an existing version to protect users and platform integrity", so pinning makes a surprise unlikely, not impossible.

2. Find every reader of the field

Search the codebase for every read of the field and every place that stores it. Response-field removals have a quiet second failure mode: stored copies. A job that writes vendor responses to a database or warehouse keeps running when the field disappears; the column just fills with nulls, and reports built on it go wrong without an error. Make two lists:

• Read paths: code that would throw, misparse, or take the wrong branch when the field is missing.
• Storage and display paths: code that will not throw but will silently store or show nothing.
• Event handlers: Stripe's entry notes the coupon is no longer auto-expanded on Discount objects within event notifications too, so webhook consumers belong on the list.

3. Choose the fix before writing it

There are usually three options, in increasing order of effort:

1. Drop the read: if the field is cosmetic and nothing branches on it, delete the code and stop storing it.
2. Read it from its new home: fields often move rather than vanish. Look for a sibling field added in the same diff window, or the replacement named in the changelog. In the example, the coupon now lives under discount.source.coupon and has to be expanded or retrieved separately.
3. Replace the dependency: if the field was the reason you called the endpoint, treat it like an operation removal and look for another source of the data.

Watch for removals that are really type changes. A field that turned from a string into an object shows up in a diff as a type change, and GitHub's versioning page lists changing the type of a response field as breaking for the same reason a removal is. That needs option 2 with a rewrite, not a null check.

4. Ship the fix with tolerant parsing

Whatever the fix, parse what the contract documents and tolerate what it may add. GitHub's versioning page says additive changes, including new response fields and new enum values, are available in all supported API versions, and Stripe's versioning page tells integrations to ignore unfamiliar fields and event types; treat new enum values the same way. Unknown fields should pass through and unknown enum values should log, not throw. While you are in the code, add a test with a recorded response that asserts the fields you depend on are present. It will not warn you about the vendor's next removal, but it will catch your own regressions against the shape you just fixed.

5. Tell the people who need to know

A response-field removal rarely needs an emergency page, but it usually needs three short notes. Internally: which feature was affected, from when, and what changed. To customers, if they saw something degrade: what, for how long, and that it is fixed. And to the vendor, if the removal was not announced or broke something the changelog did not mention: a support ticket that names the endpoint, the field and the two spec revisions from step 1, so they can check it without reproducing your setup.

6. Move the baseline forward

This step prevents a repeat. A scheduled spec diff compares the current spec against a pinned baseline. Once you have shipped the fix, move the baseline to the revision your code now supports, on the same day. In an apibreak.json manifest that is the baseline field, a commit sha or a date. If you leave it, the next run reports the same removal again, people learn that findings repeat after they are fixed, and they stop reading the report. After the move, the next finding is a new one.

The playbook on one card

1. Confirm the removal in the spec, name the two revisions, and check whether your pinned version is affected yet.
2. List read paths, storage and display paths, and webhook handlers.
3. Choose: drop the read, read it from its new home, or replace the dependency.
4. Ship the fix with tolerant parsing and a recorded-response test.
5. Send the internal, customer and vendor notes with dates and revisions.
6. Move the baseline forward on the day you deploy.

Teams that run a scheduled vendor spec diff mostly meet this playbook at step 1, with a finding and a version they have not adopted yet, instead of an error in production. The steps are the same either way; what changes is how much time you have.