ShipMsgDocs
Contents

Using the API well

Versioning

The API is versioned by date. A version’s behaviour never changes: breaking changes only arrive in a new dated version, and you choose when to move.

Pin your version

request header
ShipMessages-Version: 2026-08-21

The version used for a request is, in order:

  1. the ShipMessages-Version header on the request;
  2. otherwise your account’s default version, set in the console;
  3. otherwise the current version.

Every response names the version it used in its own ShipMessages-Version header. The SDKs require a version when you create the client, so an SDK upgrade cannot change behaviour under you. Webhook events are shaped for the version set on each endpoint.

What counts as breaking

These can happen at any time, within a version — build your integration to tolerate them:

  • new endpoints, new optional request fields and new response fields;
  • new event types and new values in lists of states or error codes;
  • longer IDs within their documented prefix.

Everything else — removing or renaming a field, changing its type or meaning, making an optional field required — only happens in a new dated version.

Deprecation

A version is supported for at least twelve months after its successor is released. While you use a deprecated version, every response carries Deprecation and Sunset headers and a Link to its changelog entry. A version past its sunset date is refused with 400. Current and past versions are listed in the changelog.