Versioning you can build against.
We version so that an integration you ship today keeps working. The rule is simple: additive changes never move the version, breaking changes get a new one, and versions run side by side so you migrate on your schedule — never ours.
Additive vs breaking
Additive — stays on /v1
These can happen at any time without a version bump, so your client must tolerate them:
- New endpoints and new optional request fields
- New fields on a response object
- New event types and new enum values
Your side of the contract: ignore unknown fields, and don't hard-fail on an enum value you haven't seen.
Breaking — becomes /v2
These only ever ship behind a new version:
- Removing or renaming a field or endpoint
- Changing a field's type or the meaning of a value
- Making a previously-optional field required, or tightening validation
- Changing default behaviour of an existing call
How a new version ships
Launching /v2 is more than a new route prefix — it's a parallel surface that reuses the same underlying platform.
Side by side
/v1 keeps serving every existing integration unchanged while /v2 is available. You're never force-migrated by a deploy.
One platform underneath
The ledger and the payment state machine are shared. A version is a request / response contract over the same core — so behaviour stays consistent across versions.
Webhooks are versioned too
Each webhook endpoint is pinned to the API version it was created on, so a payload change in /v2 never breaks a /v1 receiver.
Deprecation policy
| Stage | What happens |
|---|---|
| Announce | A version is marked deprecated in the changelog with a migration guide. Nothing breaks yet. |
| Deprecation window | Both versions run in parallel for a minimum window. Responses on the old version carry a Deprecation header and a Sunset date. |
| Sunset | Only after the window closes, and never without advance notice to every tenant still on the old version, is it retired. |
What you'll do to move to v2
Because a new version is a contract change, migrating is a code change on your side — but a scoped one:
Point at the new prefix
# from POST /v1/payment-orders # to POST /v2/payment-orders
Adopt the changed shapes
Update only the fields the migration guide calls out, re-point each webhook endpoint at /v2 when you're ready, and verify in the sandbox against the new version before you cut over live traffic.
Today the platform is on /v1 and every change so far has been additive — there is no deprecated surface. When /v2 lands, it'll be announced here first.