How to Pin an API Version for a Stable Integration

Many APIs ship breaking changes behind dated versions. If your code does not name a version, the provider may move you to a newer default and silently change a response shape. Pinning a version header makes your integration stable until you choose to upgrade. This guide pins one and upgrades it deliberately.

What you need

• An integration that calls a versioned API
• The provider's current version string from their docs
• About 8 minutes

Step 1: Find the version mechanism

Check the provider's docs for how versions are selected. Most use a request header; some use a URL segment. Note the exact current version string.

Step 2: Send the version explicitly

Add the version header to your client so every request names it. Read the value from config, not a literal scattered through the code, so one change updates it everywhere.

const API_VERSION = process.env.PROVIDER_API_VERSION ?? "2026-05-01";

export async function getOrders(): Promise<Response> {
  return fetch("https://api.provider.com/orders", {
    headers: {
      Authorization: `Bearer ${process.env.PROVIDER_KEY ?? ""}`,
      "API-Version": API_VERSION,
    },
  });
}

Step 3: Verify the pinned version is used

Make a call and confirm the response reports the version you pinned. Most providers echo it back in a response header.

Step 4: Upgrade on purpose later

When you are ready for a newer version, read its changelog, bump the config value in a branch, run your tests, and merge. The upgrade becomes a reviewed change instead of a surprise.

Result: your integration speaks one fixed API version that only changes when you decide, so provider updates stop breaking you without warning.