Versioning
The API has two layers of versioning.
- The path
/v1is the major version. It stays stable. - The contract inside
/v1is dated. The first version is2026-10-01, and it is the only one today.
Which version applies to a call
- The
X-B2B-Versionrequest header, if you send it. - Otherwise the version your client is bound to. A client is bound to the newest version when it is created, and you can change the binding in the developer portal.
- Otherwise the newest version.
Every response under /v1, errors included, carries the version that was applied:
X-B2B-Version: 2026-10-01
An unknown version in the header answers 400 validation_error with a message that lists the known
versions. It is never silently replaced by another version.
curl
curl -si https://api-sandbox.b2bgroup.dk/v1/codes/ABC-7K3Q-M8ZP/status \
-H "Authorization: Bearer $TOKEN" \
-H "X-B2B-Version: 2026-10-01" | grep -i x-b2b-version
C#
http.DefaultRequestHeaders.Add("X-B2B-Version", "2026-10-01");
var response = await http.GetAsync("/v1/codes/ABC-7K3Q-M8ZP/status");
var applied = response.Headers.GetValues("X-B2B-Version").First();
Node
const response = await fetch(`${baseUrl}/v1/codes/ABC-7K3Q-M8ZP/status`, {
headers: { ...headers, 'X-B2B-Version': '2026-10-01' },
});
console.log(response.headers.get('X-B2B-Version'));
Python
response = session.get(f"{BASE_URL}/v1/codes/ABC-7K3Q-M8ZP/status", headers={"X-B2B-Version": "2026-10-01"})
print(response.headers["X-B2B-Version"])
What can change within a version
Within a bound version we only add:
- new fields in responses,
- new optional request fields and query parameters,
- new routes, new event types and new error codes.
We never remove or rename a field, and never change the meaning of an existing field, within a
version. Write your client so it ignores fields it does not know, and handles an unknown error code
by its HTTP status.
A change that is not additive gets a new dated version. Your client stays on its bound version until you move it. Every change is listed in the changelog.
Webhooks
Webhook deliveries carry X-B2B-Version with the version the body follows.
Recommendation
Pin the version: send X-B2B-Version on every call, or leave your client bound and never send the
header. Move to a new version deliberately, first in the sandbox, after reading the changelog.