Versioning and compatibility

The public API and these docs are v1. Each service's API lives under /<service>/v1/, and the storefront paths under /api/... are the v1 contract the SDK is built on.

#What we never do within v1

• remove an endpoint, a field or an accepted value;
• rename a field or change its type;
• change what a status code or error code means;
• make an optional parameter required.

#What we may do within v1

• add endpoints, optional parameters and response fields;
• add new error codes for new situations;
• add values to lists your code should treat as open-ended.

Write a tolerant reader: ignore fields you do not know, and do not depend on the order of keys.

#When something must change

A breaking change ships as a new version (v2) beside the old one. The old version keeps working through a published deprecation period, responses carry a Deprecation header that links to the migration guide, and these docs keep every published version readable with a banner pointing to the current one.