Versioning

/api/v2 is permanent. Breaking changes are published as revisions. Your API key is pinned to the revision that was current on the day we issued the key. You get that revision on every call. The Api-Revision header overrides the pin for one request. The portal shows the pin on the key and lets you move it when your integration is ready.

curl "{BASE_URL}/orders/{orderId}" \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Api-Revision: 2026-08-21.auk'

Every response echoes back the revision that produced it, so you can always tell which contract you are reading:

Api-Revision: 2026-08-21.auk

Revisions

A revision is a date and a name — 2026-08-21.auk. Names run alphabetically, so the ordering is readable without a lookup. The full value is the only accepted form. A date or a name on its own is rejected with 400 unknown_api_revision.

Every revision has an OpenAPI document of its own, and that is the one to generate a client from. The reference on this site documents the current revision, which is also served as /bundled_openapi.json.

2026-09-01.bullfinch

Current. OpenAPI document

• Removed the deprecated order pricing amounts in major currency units. Read the integer *Minor field instead: subtotalMinor, taxAmountMinor, totalMinor, totalDiscountsMinor, recurringAmountMinor, initialInvoiceAmountMinor, amountMinor.
• Removed netPrice, currencyOptions and balance, the deprecated amounts in major currency units. Read netPriceMinor, currencyOptionsMinor and balanceMinor instead.
• Removed Price.boundMonths. Read bindingContract.duration instead, which carries the unit alongside the count.
• Removed POST /orders/{orderId}/calculate-price. The order endpoints return the current price as pricing, and the platform calculates it again each time the order changes. The removed call only read back what GET /orders/{orderId} returns.

2026-08-21.auk

Supported until 2026-12-01. OpenAPI document

• The baseline.

What we will not do to you

Publishing a revision does not move you onto it. Your key keeps the revision it was issued with, and we never move that pin. A revision that we publish tomorrow reaches you only when you ask for it, with the header, with a new key, or in the portal.

The exception is the retirement date in the list. When the revision your key is pinned to retires, your calls resolve to the oldest revision that is still supported. That is a breaking change on a published date, not on a deploy.

A call that carries no API key resolves to the oldest supported revision.

A webhook has a revision of its own. A delivery is not a call, so it cannot take the pin of a key. One setting decides the shape of every webhook payload that we send to you. It starts at the oldest supported revision, and we never move it. To read it or to move it, open Admin > Advanced > Webhooks in the portal. Every delivery repeats the revision that produced it in the apiRevision field of the envelope. Webhooks has the detail.

Additive changes are not revisions. We add response fields, response enum values and new endpoints without cutting a revision, and they reach every revision at once. Write clients that ignore unknown fields and handle unknown enum values, because a new value can appear on the revision you are pinned to.

A breaking change only happens in a new revision. These changes are breaking: a field that is removed or renamed, an endpoint that is removed, and a field that changes type or meaning.

You get at least three months. A revision is served for a full quarter after its replacement ships. The day it stops is published here as soon as that replacement lands.

Upgrading

Send the new revision on a single non-production call first and compare the response with what you store. When it matches, set the header everywhere. Nothing changes for you until you send it.

To move the key itself, open Admin > Advanced > API Tokens in the portal. The key lists the revision it is pinned to, and how far that revision is behind the current one. Change API revision shows what each hop changed before you commit to it.

Upgrading is the step-by-step version. It lists every field and operation that each revision changed, so you can check it against the calls your integration makes.