Shopify · api · fg-0334

Shopify responses change shape without a deploy because the pinned API version was retired and Shopify fell forward

X-Shopify-API-Version response header shows a newer version than the one in the request URL

Verified 2026-10-15 · Confirmed by 0 builders · Trust 50/100

Cause

Each quarterly version stays accessible for about 12 months. After that, requests for it are served by the oldest version still supported, so breaking changes arrive on their own schedule.

Fix

Read the X-Shopify-API-Version header on responses and webhooks, alert when it differs from what you pinned, and move the pin plus the shopify.app.toml webhooks api_version forward every quarter.

Apply

# shopify.app.toml
[webhooks]
api_version = "2026-10"

// client
const res = await fetch(`https://${shop}/admin/api/2026-10/graphql.json`, opts)
if (res.headers.get('x-shopify-api-version') !== '2026-10') alertVersionDrift()

Affects: All versioned Shopify APIs and webhooks; 2025-10 stops being accessible on 2026-10-16 15:00 UTC, 2026-01 on 2027-01-16

Sources

https://shopify.dev/docs/api/usage/versioning

Have your agent know this before it fails

claude mcp add --transport http footgun https://getfootgun.com/api/mcp