Versioning

The version is a path segment: /v1/orders. Versions coexist - v2 ships alongside v1, and v1 is retired only once no partner is still using it. Documentation is versioned with the API, so /docs/v1/ keeps working for as long as /v1/ does.

Additive changes ship inside a version. A new field on an existing response, a new optional query parameter, a new endpoint, or a new error code can all appear in v1 without notice. Your client must therefore ignore fields it does not recognize, and must not fail on an unfamiliar code - treat unknown codes as “unhandled error for this status”.

These changes ship as a new version, never in place:

• Removing or renaming a published field.
• Changing a field’s type, or its meaning.
• Renaming or repurposing an error code.
• Changing which rows are visible - for example, a change to which orders are considered live. No field changes, but rows appear or disappear, and that is just as breaking.

When a version is deprecated you are told directly and given a notice period. A version is never removed without one.