Versioning

The version is in the path: /v1. Within /v1 the API only grows; nothing is removed, renamed or retyped. What follows is our commitment on how /v1 changes, not a behaviour the API enforces at runtime.

The API is described by an OpenAPI 3.1 file at /openapi/merchant-api.json: it is the same file the API Reference is built from and it refreshes when the API changes, so a client generated from it follows the additions below.

What can change without notice

New endpoints, new optional parameters, new response fields, new webhook topics and new storefront event types may appear at any time. Clients must ignore fields they do not know, and a webhook receiver must accept a topic it does not know (answer 2xx and drop it, or subscribe only to the topics you handle).

What needs a deprecation window

Nothing is removed, renamed or retyped, and no input becomes required, without a deprecation window. A deprecated endpoint or field keeps working for at least 90 days and answers with Deprecation and Sunset headers naming the date; the replacement is available for the whole window. Nothing is deprecated today, so no route sends either header yet.

Watch for these headers in your logs; they are the first signal that a call you make is on its way out.

Webhooks and storefront events

Webhook payloads and storefront events carry api_version: "v1" in their envelope. They follow the same rule: fields are added, never removed or retyped, within v1.