The API version your vendor switches off in 90 days

Nobody broke it. It broke anyway.

There is a category of outage that makes people defensive, because the honest answer to "what changed on our side" is "nothing". A workflow that shipped fourteen months ago, has not been edited since, and worked yesterday stops working at seven in the morning and returns 410 on every call. No deployment, no config change, nobody poking at the scenario. The vendor turned off the API version it was built against, on the date they announced nine months earlier.

We see this a few times a year, usually at wholesalers and logistics operators, usually on a carrier or ERP integration, and almost always with the same root cause. The announcement arrived. It just never reached anyone who could act on it.

Your integrations have expiry dates you never wrote down

An automation is an agreement between systems owned by other companies. Those companies ship new API versions, retire old ones, and run that clock on their schedule. Some publish dated versions four times a year and guarantee each one twelve months of life. Others deprecate whenever it suits their roadmap. Carriers occasionally have a hard regulatory date they cannot move even if you beg.

Do the arithmetic on a normal order-to-ship process: shop, ERP, carrier, customs portal, accounting, transactional email, one or two data services. Seven external interfaces, each retiring something roughly once a year, means a deprecation notice lands in someone's inbox every couple of months. If you have never received one, that is not a sign of stability. It means the notices are going somewhere you are not looking.

The notice problem is an addressing problem

Vendors are not sneaky about this. They send email, they keep a changelog, and the better ones set `Deprecation` and `Sunset` headers on every response so the warning travels inside the integration itself. Where it falls apart is the recipient.

Technical accounts get created in a hurry, against whatever mailbox was handy: a shared info@ address, or the personal account of whoever set up the connection two years ago and now works in a different department. When the notice does reach a human, it often reaches someone in sales who reads "Shipment API v2 will be discontinued on October 1" and correctly concludes there is no action they personally can take.

Even the right person hits a wall immediately. Which of our automations calls that version? In most companies that ask us for help, no document answers that. So nobody acts, because acting would mean opening thirty scenarios to check.

The loud failures are the lucky ones

A 410 is blunt but honest: the workflow stops, someone notices, the customer complains by lunch. The changes worth fearing are the ones that keep returning 200.

Say a field quietly disappears from the response. Your workflow starts writing empty delivery dates into the ERP. Or an enum gains a value your branch logic has never heard of, and every shipment in that state drops silently into the else path. Or a default page size falls from a hundred to fifty, and you stop seeing half of the day's orders. Nothing turns red, the logs stay green, and you find out at month-end when the numbers refuse to reconcile. Then you spend a week working out how far back it goes.

You do not catch those with error alerts. You catch them by reading what your vendors publish before it takes effect.

"We will deal with it when it breaks"

This objection comes up in nearly every conversation, and it is not stupid. Why maintain a list when the outage announces itself and the migration takes half a day anyway?

The maths works while the outage stays cheap. The wholesaler had four hundred shipments waiting that Tuesday. Getting credentials for the new version, remapping the fields and testing the workflow took two days, during which two staff generated labels by hand in the carrier's portal and pasted tracking numbers back into the ERP, with the error rate that implies. The migration itself would have taken three hours in September, on an empty desk. Same work either way. What they paid extra for was two days of manual labour, late deliveries and the complaints that followed.

There is a second effect we see often enough to plan around: people migrate badly under pressure. Do it on the outage day and you take the first mapping that fits, skip the test, and install your next silent bug while you are at it.

What good operations look like here

The fix is unglamorous, and it costs about a day.

Start with the inventory: one row per connection, listing the workflow, system, endpoint, version, account, credential location, and known retirement date. Half a day for a mid-sized stack. After that, the question that used to take a week of archaeology takes two minutes.

The versions themselves hide in three places: the URLs of your HTTP steps, usually as `/v2/` in the path; headers like `API-Version` that someone set once at build time and never looked at again; and the connection settings of prebuilt modules, which often do not surface the version at all. That last one is the awkward case, because you are not the one deciding which version gets called. Your date then depends on two schedules, the vendor's and your automation platform's. The big platforms usually keep up, but they do it on their timeline and without telling you.

Every technical account belongs to a distribution address with at least two humans behind it, one of whom actually maintains the automations. Personal mailboxes rot when people move on, and shared info@ addresses get ignored by everyone at once.

Where a vendor offers versioned endpoints, name the version explicitly instead of pointing at whatever is current. Running on latest means every breaking change arrives overnight, unannounced, in production. Pinning does not remove the work, it moves the surprise to a date you choose.

If the vendor sends `Deprecation` or `Sunset` headers, have the workflow check for them and post once into your ops channel when a date shows up. Ten minutes of build time, and the warning lands where somebody is already looking.

Known retirements go in the shared calendar like maintenance windows, with eight weeks of lead time. Do the migration on an ordinary Tuesday against the vendor's sandbox. Migrating on the cutover date turns a planned change into an incident.

Automation is not a project you finish

The wholesaler's shipping workflow was well built. It ran cleanly for fourteen months and then died at seven in the morning without anyone making a mistake. The only failure was that nobody on their side was reading what the vendor had been saying since January.

If you cannot say today which of your automations depends on which API version, start there. An inventory is dull, and it earns its keep exactly once: when it turns a week of panic into a two minute lookup, before the outage rather than during it.