> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/vantage-api/changelog.md).

# Changelog

Every Vantage API version, newest first, with its breaking changes and the non-breaking changes shipped while it was the latest.

Each Vantage API version is named by a date. Under each version:

* **Breaking** changes apply only once your account is pinned to that version, or when you send it in the `X-Terra-Version` header. See [Versioning](https://docs.tryterra.co/vantage-api/versioning.md) for how to upgrade.
* **Non-breaking** changes reach every version as soon as they ship, with no upgrade needed. They are listed by the date they shipped, under the version that was the latest at the time.

Enums can gain new values without a new version. Treat a value you don't recognise as described in the [API reference](https://docs.tryterra.co/reference/vantage-api).

## `2026-10-29` (latest)

### Breaking

* **Catalogue:** a product's `description` is a [rich text document](https://docs.tryterra.co/vantage-api/rich-text.md), a JSON tree with a node for every Markdown construct, instead of a string. A product without a description has an empty document. Variant and product type descriptions are still strings.

### Non-breaking

#### 2026-10-29

* **Catalogue:** each entry in a variant's `biomarkers` has a `summary`, a rich text `description` and a `source_url`: a plain-language explanation of the biomarker, copied from the U.S. National Cancer Institute or MedlinePlus, and the page it came from. All three are `null` when no source explains the biomarker. Every API version serves them. See [Core concepts](https://docs.tryterra.co/vantage-api/core-concepts.md#the-catalog-product-types--products--variants).

## `2026-10-15`

### Breaking

* **IDs:** product, variant, image and product type IDs are decimal strings, such as `"42"`, instead of numbers. A request's `variant_id` accepts a string or a number.
* **Orders:** `currency` is the ISO 4217 code (`USD`, `EUR`, `GBP`) instead of the numeric code (`840`, `978`, `826`).
* **Orders:** `item_status` is a string (`pending_shipment`, `in_transit`, `delivery_attempted`, `delivered`) instead of an integer. It is omitted until the kit has a shipping status.
* **Lists:** `GET /orders`, `GET /results` and `GET /webhook-deliveries` return `data`, `has_more` and `next_cursor`, all always present. Previously the items were under `orders`, `results` or `deliveries`, with no `has_more`, and `next_cursor` was omitted on the last page. Catalogue routes and `GET /labs` are unpaginated and still return a bare array.
* **Idempotency:** replaying a request with the same `Idempotency-Key` and body returns `200` instead of `201`.
* **Idempotency:** an `Idempotency-Key` longer than 255 characters returns `400` with code `idempotency_key_too_long`.
* **Errors:** `type` URIs are `https://docs.tryterra.co/vantage-api/errors/<slug>` instead of `https://api.terra-diagnostics.com/errors/<slug>`.
* Webhook payloads are unchanged.

### Non-breaking

#### 2026-10-29

* **Errors:** most credential refusals are `application/problem+json` with a `code`, whatever the version: `unauthorized` (`401`) for a missing, invalid, expired or revoked key or token, `scope_missing` or `audience_restricted` (`403`), and `authorization_unavailable` (`503`, retry later). The status codes are unchanged. A few keep the previous format, so choose the schema by `Content-Type`. [Errors](https://docs.tryterra.co/vantage-api/errors.md#credential-refusals)

#### 2026-10-28

* **Orders:** `GET /orders` accepts `order_id`, `variant_id`, `recipient_name` and `recipient_email` filters. `status` takes several statuses.
* **Results:** `GET /results` accepts `variant_id` and `client_order_reference_id` filters. `status` and `order_id` take several values.
* **Lists:** on `GET /orders` and `GET /results`, a list filter takes up to 100 values, repeated or joined with commas, and matches any of them. `order=asc` returns the oldest first. Send the same `order` and filters with every page's cursor.
* **Webhooks:** a webhook URL with credentials in it, such as `https://user:pass@example.com`, returns `400`.

#### 2026-10-27

* **Catalogue:** an environment can be limited to the UK or US market. Once its markets are set, catalog reads leave out products not sold in them, the variants route returns `404` for one, and ordering one returns `403`. Until then it sees every market. See [Markets](https://docs.tryterra.co/vantage-api/core-concepts.md#markets).
* **Webhooks:** every event is recorded when it happens. One that could not be sent straight away is sent later under the same `event_id`, so it can arrive after a newer event for the same order: order them by `X-Terra-Ordering-Timestamp`.
* **Webhooks:** in `GET /webhook-deliveries`, `attempts` counts every HTTP attempt across all retries, and a dead-lettered delivery carries its last status code, or `null` when the last attempt got no response.
* **Webhooks:** creating an order sends `order.status_changed` for `order.payment_processing`, and for `order.payment_complete` when payment is taken as the order is created. Previously these two statuses could only be read from the order.

#### 2026-10-09

* **Results:** `results_status` can be `results.not_applicable`, for a product that never produces a result. It never changes, and no results webhook is sent for it.

#### 2026-10-08

* **Catalogue:** variants have a `collection_visit`, `home_phlebotomy` or `clinic`, when the sample is taken at a clinician visit. It is omitted for self-collected kits.
* **Catalogue:** `collection_method` can be `automatic_capillary`, a self-collected capillary sample from a push-button device.
* **Orders:** order items have a `collection_visit` with `type`, `status` (`booking`, `requested` or `booking_failed`) and `scheduling_url`.
* **Orders:** a home-visit item needs an `AT_HOME` order with a valid phone number, or the request returns `400`. A clinic-visit item is ordered as `GO_TO_LAB` with a `shipping_address`, and can have the status `awaiting_clinic_invite`.
* **Orders:** `POST /orders` can return `422` with code `order_not_approved` for a test that needs clinician approval. The same `Idempotency-Key` and body can be retried.
* **Orders:** kit activation returns `409` while another activation of the same kit is in progress. Retry shortly.
* **Webhooks:** `results_ready` carries `amended: true` when it is a corrected release of a result already delivered. Fetch the result again.

#### 2026-10-02

* **Orders:** `GET /orders` accepts `until` and `client_order_reference_id` filters.
* **Results:** `GET /results` accepts `is_acknowledged`, `order_id`, `since` and `until` filters.
* **Lists:** a `limit` above 100 is treated as 100 instead of returning `400`. An exactly full last page no longer returns a `next_cursor`.
* **Idempotency:** a request that failed without creating anything, such as a `402` or a `403` catalogue rejection, can be retried with the same `Idempotency-Key` and body.
* **Payments:** `402` responses carry a `code`: `payment_method_missing`, `card_declined` or `payment_authorization_failed`.
* **Webhooks:** `POST /webhook-events/resend` resends a delivered event for up to 30 days, and `POST /webhook-events/generate` sends a test event marked `"test": true`. Both need the `vantage:write` scope and accept `?dry_run=true`.
* **Webhooks:** every delivery carries `X-Terra-Ordering-Timestamp`, the Unix time in milliseconds the event was emitted. It is the same on every retry.
* **All responses:** carry an `X-Request-Id` header. Include it when you contact support.
* **Fixed:** in result FHIR bundles, every reference now resolves inside the bundle, and each bundle includes an `Organization` entry.

## `2026-10-01`

### Breaking

Catalogue variants carry typed fields. See [Core concepts](https://docs.tryterra.co/vantage-api/core-concepts.md).

* **Catalogue:** variant `variant_name` is renamed to `name`.
* **Catalogue:** variant `descriptive_attrs_override` is replaced by `description`.
* **Catalogue:** variant `variant_defining_attrs` is replaced by `turnaround_days` and `collection_method`.
* **Catalogue:** variant `variant_availability` is replaced by `availability`, a string: `unknown`, `in_stock` or `out_of_stock`.
* **Catalogue:** variant `requires_activation` is added.
* **Catalogue:** product `model_descriptive_attrs` is removed. Its collection method is now `collection_method` on each variant.
* **Catalogue:** product `availability` is a string instead of an integer.
* Webhook payloads are unchanged.

### Non-breaking

#### 2026-10-01

* **Catalogue:** product and variant `images` are populated.

#### 2026-09-29

* **Versioning:** your account is pinned to the latest version on its first request, and you can change the pin in the dashboard.

#### 2026-09-28

* **Versioning:** the `X-Terra-Version` header picks the version a request is served in. Every response and webhook delivery carries it, and an unknown value returns `400` with code `invalid_api_version`.

## `2026-09-27`

The first version. Catalogue variants carry attribute bags and integer availability.
