---
title: Versioning
description: Pin your integration to an API revision so a breaking change never reaches you unannounced.
---

`/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.
```bash
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:
```http
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`](/bundled_openapi.json).

### 2026-09-01.bullfinch

**Current.** [OpenAPI document](/openapi/2026-09-01.bullfinch.json)

- 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](/openapi/2026-08-21.auk.json)

- 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](/api-reference/webhooks.md) 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](/api-reference/upgrading.md) 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.