API versioning

Current API version: 2026-10

Supported versions: 2026-10.

Each dated API version covers all partner endpoints and webhooks, and sets the request rules, response shapes and webhook formats. The v1 segment in the base URL stays fixed.

Every platform is pinned to one supported dated API version, and a new platform starts on the current version. Snapcaster builds responses to your sellers’ API requests, and the webhooks it sends your platform, at that version. Deploying a Snapcaster release does not change your pin.

A response uses the version your request named in X-Snapcaster-Api-Version, or your pin when it named none. No API response names its version, so to read your pin, send POST /webhooks/test and read api_version on the webhook.test your receiver gets.

When Snapcaster publishes a new version, test it with the override header, then email info@snapcaster.gg to move your pin. Webhooks already queued for delivery keep the version they were queued at.

To get one response at another supported version, send X-Snapcaster-Api-Version: <version> on that request. The override never changes the platform pin or any webhook. A version Snapcaster does not support returns HTTP 400 UNSUPPORTED_API_VERSION with the list of supported versions.

Normal traffic needs no override, because every request without the header gets your platform pin. If a request keeps sending a version after your pin moves, it still gets that version until Snapcaster retires that version, and from then on the request returns UNSUPPORTED_API_VERSION.

curl --request GET \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/me' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY" \
  --header 'X-Snapcaster-Api-Version: 2026-10'

Every webhook envelope includes api_version, the version Snapcaster used to build data. Every retry of an event_id carries the same version, and while your pin moves, it tells your receiver which parser to use. If your receiver handles an event but cannot parse its api_version, answer non-2xx and change nothing. Snapcaster retries it like any body that is not a usable event, so deploy a parser for that version before the retries end.

Additive changes never create a new version and need no change to your integration. They include new optional fields, new event types, new endpoints and new values in a vocabulary the reference marks “closed vocabulary, extended additively”. Two fields carry that mark: address_verification.status on an order and reason on order.updated. Ignore fields and event types you do not recognize, and accept a value you do not recognize in either marked field.

Snapcaster publishes a new dated version when it removes or renames a field, changes its type or meaning, or makes a value required. A breaking change reaches your platform only after your pin moves to the new version. Snapcaster retires a supported version only after every platform has moved off it, and with at least 90 days’ written notice. The changelog records each version and the action it requires.