Pin their API version and watch for its end

How to do it

Without a pinned version, the provider can change the answer under you on its own date. Upgrade on purpose, after the tests pass on the new version, as pin the provider's API version shows for payments. Read Deprecation and Sunset on every answer, and send one warning per endpoint a day to the team's alert channel. Subscribe a shared team address to each provider's changelog and status page. How to send these headers from your own API is in announce deprecation and sunset in headers.

Examples

JavaScript example

const CARRIER_API_VERSION = '2026-06-01';

async function carrierFetch(path, init = {}) {
  const response = await fetch(`${CARRIER_URL}${path}`, {
    ...init,
    headers: { ...init.headers, 'carrier-version': CARRIER_API_VERSION },
  });
  const sunset = response.headers.get('sunset');
  if (response.headers.has('deprecation') || sunset) logger.warn({ path, sunset }, 'carrier endpoint deprecated');
  return response;
}

Python example

CARRIER_API_VERSION = "2026-06-01"

def carrier_request(method: str, path: str, **kwargs) -> httpx.Response:
    headers = {**kwargs.pop("headers", {}), "Carrier-Version": CARRIER_API_VERSION}
    response = httpx.request(method, f"{CARRIER_URL}{path}", headers=headers, **kwargs)
    sunset = response.headers.get("Sunset")
    if "Deprecation" in response.headers or sunset:
        logger.warning("carrier endpoint deprecated", extra={"path": path, "sunset": sunset})
    return response

How to check

Each adapter has one version constant, and every request in its tests carries it. Make the provider's fake answer with a Sunset header. The adapter logs a warning that names the endpoint and the date.

Sources

• RFC 9745 The Deprecation HTTP response header field
• RFC 8594 The Sunset HTTP header field

Related rules

• Pin the provider's API version in Payments
• Announce deprecation and sunset in headers in API design