Shipping rates fail after a vendor retires an API version

On-call incidentEasy15 min

Your task

At 00:05 UTC on the first of the month, checkout's shipping step starts failing. Customers see "We could not calculate shipping", and conversion drops to near zero for orders that need shipping; digital orders still work. The shipping-rates client logs 410 Gone from https://api.carrier.example/v1/rates on every call, with the body:

{"error": "API v1 was retired on 2026-11-01. Use /v2/rates."}

The vendor's status page is green. Searching email, you find six deprecation notices sent since May, all to the address of an engineer who left in the spring. Checkout has a feature flag, shipping_flat_rate_fallback, that charges a flat 9.99 per order instead of calling the vendor. There is no v2 client code in the repo yet. How do you triage and mitigate?

It covers

  • Third party api
  • Deprecation
  • Fallback