Skip to content
Docs

Versioning

How the API is versioned, what counts as a backwards-compatible change, and how to build an integration that keeps working.

The current API version is 2026-10-01, served under /api/v1. Every response carries it in the Api-Version header, and every event and webhook payload in its api_version field.

Backwards-compatible changes

We add to the API without a new version. Your integration must tolerate:

  • new endpoints, and new optional request parameters;
  • new fields in responses and event payloads (and new values in metadata-like maps);
  • new event types (endpoints subscribed to ["*"] receive them);
  • new error codes, and new values of fields documented as open-ended (for example OrderEvent.type, carrier codes);
  • new enum values for statuses — handle unknown values gracefully (for example treat an unknown order status as "in progress");
  • changes to error messages (branch on code, never on message);
  • the order of fields in JSON objects and of keys in maps.

Breaking changes

Removing or renaming a field, changing a type or the meaning of a value, or making an optional parameter required would break integrations. Such changes ship only in a new dated API version, announced in the changelog and by email well ahead of time, with a migration guide and a transition period.

Building a resilient integration

  • Parse responses leniently: ignore unknown fields and unknown event types.
  • Validate the fields you depend on, and log (don't crash on) unexpected values.
  • Pin your SDK or HTTP client code to the fields documented in the objects reference.
  • Watch the changelog — or the api_version of incoming events.