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 beyond the changelog:
- new endpoints, new optional request fields, new query filters,
- new response fields (anywhere, including nested objects),
- new enum values and new event types,
- new blocker
types and errorcodes.
Write clients that ignore unknown fields and treat unknown enum values as "other".
What will never change within v1
- Existing fields are not renamed, removed, or retyped.
- Existing enum values 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 a changelog entry, 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 on the changelog and 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 and changelog with its replacement.