Browse the guides
Versioning & Deprecation
v1 in the path; additive changes only; breaking changes ship as a new version with at least 12 months of overlap.
The version is in the path: https://api.shopcommander.com/v1/….
What can change within v1
Additive changes ship without notice and are reflected in the published openapi.json:
- new endpoints, new optional request fields, new query filters,
- new response fields (anywhere, including nested objects),
- new values for extensible response strings and new event types,
- new blocker
types and errorcodes.
Requests are closed: unknown request fields are rejected, and request enums
remain strict. Responses are open/additive: clients must ignore unknown fields.
Extensible response values are represented as string in OpenAPI, with
x-known-values preserving the current vocabulary for documentation and
tooling. Treat any other string as "other" and preserve it when possible.
True constants and discriminators such as object: "customer",
api_version: "v1", and status: "queued" remain closed.
What will never change within v1
- Existing fields are not renamed, removed, or retyped.
- Existing
x-known-valuesentries are not removed. - Required-ness of request fields does not tighten.
- Ids, prefixes, and the error envelope are stable.
These promises are enforced mechanically: the published openapi.json is frozen in Shop Commander's repository, and every deployment is checked against it — a breaking change cannot ship without a new version number, and response shapes are pinned by contract tests.
Breaking changes
A breaking change is released as v2 alongside v1. v1 then runs for at least 12 months, with reminders in the shop's Developer settings, before it is retired. Webhook envelopes carry api_version so a receiver can tell which contract a delivery follows.
Deprecations
A deprecated field or endpoint keeps working for the remainder of the version and is marked in the reference with its replacement.