Versioning

How Vantage API versions work: choosing a version per request, your account's pinned version, versioned webhooks, upgrading, and the changelog.

Versions are dates

Each Vantage API version is named by a date, such as 2026-10-01. A breaking change ships under a new date. Additive changes, such as a new field or a new endpoint, land in every version.

Choosing a version

Each request is served in one version, picked in this order:

1. The X-Terra-Version header on the request, if you send one.

2. Your account's pinned version, if it has one.

3. Otherwise, the latest version.

Every response carries an X-Terra-Version header stating the version it was served in.

curl 'https://vantage-sandbox.tryterra.co/api/v1/products/1' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY' \
  -H 'X-Terra-Version: 2026-10-01'

An unknown version returns 400 with code invalid_api_version. The detail lists the supported versions. See Errors.

Webhooks

Webhook deliveries use your account's pinned version, or the latest version if your account has no pin. The request header does not apply to them. Each delivery carries the version it was rendered in as an X-Terra-Version header.

If you process deliveries asynchronously, store the X-Terra-Version header with the body, so the worker knows which shape it is reading. See Webhooks.

Upgrading

Most accounts have no pin and always receive the latest version. If your account is pinned to an older version:

1. Send X-Terra-Version with the new date on individual requests, and check your code handles the new shape.

2. Update your webhook handler to accept the new shape, using the X-Terra-Version header on each delivery to tell the two apart.

3. Ask Terra to move or remove your account's pin. There is no self-serve setting yet.

Once the pin changes, requests without the header and all webhook deliveries use the new version.

Changelog

2026-10-01

Catalogue variants carry typed fields. See Core concepts.

• Variant variant_name is renamed to name.

• Variant descriptive_attrs_override is replaced by description.

• Variant variant_defining_attrs is replaced by turnaround_days and collection_method.

• Variant variant_availability is replaced by availability, a string: unknown, in_stock or out_of_stock.

• Variant requires_activation is added.

• Product model_descriptive_attrs is removed. Its collection method is now collection_method on each variant.

• Product availability is a string instead of an integer.

• Webhook payloads are unchanged.

2026-09-27

Baseline. Catalogue variants carry attribute bags and integer availability.