Using the API

Versioning

Within v1, the contract grows additively except for one documented private-beta correction. Build a client that ignores what it doesn't recognize and it will keep working through additive releases.

The compatibility promise

• Additive within v1 after the documented private-beta correction. New fields, new endpoints, and new error codes may appear at any time. On 2026-08-11, while v1 remained in private beta, Peak PIM removed the metaobject-definition label-translation endpoint and narrowed get_master_translations_v1 to products and collections because those labels were a Peak PIM-only concept rather than Shopify translation resources. The changelog entry is the explicit exception.
• Ignore unknown response fields. A client must tolerate fields it does not know; treating an unexpected key as an error is the one way to break yourself on a compatible release.
• Unknown error codes degrade to their HTTP status. The published code set only ever grows — handle a code you don't recognize as a generic failure of its status (an unknown 4xx: don't retry unchanged; an unknown 5xx: retry with backoff).
• Existing meaning does not shift. Outside that private-beta correction, a field removal, retype, or semantic change is a breaking change and does not ship inside v1.

How a breaking change would ship

After the private-beta exception above, a breaking change ships as /api/v2, not as a mutation of v1. When that day comes:

• v1 responses gain Deprecation and Sunset headers announcing the timeline.
• The changelog carries the announcement and the migration path.
• v1 keeps working through the published sunset window — the headers are the machine-readable countdown.

The contract and its changelog

• /api/openapi.yaml — the machine-readable contract, an OpenAPI 3.1 document. What is in the spec is the promise; generate clients from it rather than hand-transcribing shapes.
• /changelog — every change to the published contract gets an entry, newest first, including notes for integrators.

Versioning on the MCP side

The MCP connector carries the same promise in tool names: every tool is suffixed _v1 (list_products_v1, publish_master_v1, …). Within the suffix, tool inputs and outputs change additively, exactly like the REST surface. The same 2026-08-11 private-beta correction narrowed get_master_translations_v1 to products and collections; after that exception, a breaking tool-contract change ships under a new versioned name rather than changing the existing tool underneath connected assistants.