# Versioning

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

Source: https://swaglists.com/docs/versioning

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](https://swaglists.com/docs/changelog.md) 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](https://swaglists.com/docs/objects.md).
- Watch the [changelog](https://swaglists.com/docs/changelog.md) — or the `api_version` of incoming events.