Guides

Migrating to v2

What changed between the 2025-11-01 and 2026-06-01 API versions, and how to move across.

Migrating to v2

The 2026-06-01 API version is the first to be called v2. It is not a rewrite — most integrations need two or three changes.

Your API version is pinned per key, so you can migrate one service at a time. Create a new key pinned to 2026-06-01, migrate the caller, then retire the old key.

Breaking changes

Amounts are integers, not decimal strings

The signature header dropped v0

Empty payloads are rejected

Non-breaking additions

streamKey — opt-in ordering. Absent means unordered, exactly as before.
apiVersion on the event body, so a consumer can tell which shape it is reading.
GET /v1/deliveries accepts status and since filters.

Migration checklist

Create a v2 key

Settings → API keys → Create key, pinned to 2026-06-01.

Update the amount field

Search your handlers for payload.amount and switch to amountCents.

Parse the signature header by key

Split on , then on =, and look up v1 by name.

Cut over and verify

Deploy, then watch exhausted on the metrics endpoint for an hour.

Support window

The 2025-11-01 version is supported until 1 March 2027. After that, keys pinned to it will receive 410 api_version_retired.

See the Changelog for the full version history.