> 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/reference/vantage-api/products.md).

# Products

The test products and variants you can order, and the catalogue selection your environment offers.

## List all product types

> Lists the diagnostic test categories, such as blood tests and DNA tests. Pass a type's \`id\` to \`GET /api/v1/products/{id}\` for its products.

```json
{"openapi":"3.2.0","info":{"title":"Terra Vantage API","version":"2026.11.11.1"},"tags":[{"name":"products","summary":"Products","description":"The test products and variants you can order, and the catalogue selection your environment offers."}],"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."},"DevIDHeader":{"type":"apiKey","in":"header","name":"dev-id","description":"Environment owned by the data token's customer and within its audience."}},"parameters":{"ApiVersion":{"name":"X-Terra-Version","in":"header","required":false,"description":"The API version to serve this request in. Defaults to your account's pinned version; an account is pinned to the latest version on its first request.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}},"RequestId":{"description":"A UUID generated for this request, unique per request and never taken from the caller. Quote it to support to find the request.","schema":{"type":"string","format":"uuid"}}},"schemas":{"ProductType":{"type":"object","properties":{"description":{"type":"string"},"id":{"type":"string","description":"Decimal string."},"name":{"type":"string"}}},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}},"AuthenticationError":{"description":"Authentication error response (401)","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","status","title","type"]},"Refusal":{"description":"A credential refusal from Terra's edge, served as `application/problem+json` in every version. The HTTP status is not repeated in the body.","type":"object","required":["type","title","instance","detail","code"],"properties":{"type":{"type":"string"},"title":{"type":"string","description":"The HTTP status text, lowercased."},"instance":{"type":"string","description":"The request path, with its query."},"detail":{"type":"string"},"code":{"type":"string","description":"Why the credential was refused: `unauthorized` (401) for a missing, invalid, expired or revoked credential; `scope_missing` (403) for one that lacks the scope this operation requires; `audience_restricted` (403) for one not granted for this dev-id; `authorization_unavailable` (503) when the credential could not be checked, so retry later.","enum":["unauthorized","scope_missing","audience_restricted","authorization_unavailable"]}}}},"responses":{"InvalidApiVersion":{"description":"Unsupported `X-Terra-Version`; the problem carries code `invalid_api_version` and lists the supported versions in `detail`.","headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"paths":{"/api/v1/products":{"get":{"operationId":"listProductTypes","summary":"List all product types","tags":["products"],"description":"Lists the diagnostic test categories, such as blood tests and DNA tests. Pass a type's `id` to `GET /api/v1/products/{id}` for its products.","parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Successfully retrieved product types","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}}}}},"400":{"$ref":"#/components/responses/InvalidApiVersion"},"401":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Unauthorized - invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"403":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"The credential lacks the scope this operation requires (code `scope_missing`) or is not granted for this dev-id (code `audience_restricted`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"500":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}}}}}}}
```

## Set catalog selection

> Sets which products your catalogue reads return and which you can order, returning how many are enabled.\
> \
> \- It replaces the whole selection: listed products become enabled, and every other product disabled.\
> \- With no selection saved, every product is enabled.\
> \- Products added to the catalogue after your last save are enabled until you save again.\
> \- Disabled products are left out of catalogue reads, and ordering one returns 403.

```json
{"openapi":"3.2.0","info":{"title":"Terra Vantage API","version":"2026.11.11.1"},"tags":[{"name":"products","summary":"Products","description":"The test products and variants you can order, and the catalogue selection your environment offers."}],"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."},"DevIDHeader":{"type":"apiKey","in":"header","name":"dev-id","description":"Environment owned by the data token's customer and within its audience."}},"schemas":{"UpdateCatalogSelectionRequest":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","description":"Products to enable; everything else is disabled.","items":{"type":"string"}}}},"UpdateCatalogSelectionResponse":{"type":"object","required":["enabled_count"],"properties":{"enabled_count":{"type":"integer"}}},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}},"Refusal":{"description":"A credential refusal from Terra's edge, served as `application/problem+json` in every version. The HTTP status is not repeated in the body.","type":"object","required":["type","title","instance","detail","code"],"properties":{"type":{"type":"string"},"title":{"type":"string","description":"The HTTP status text, lowercased."},"instance":{"type":"string","description":"The request path, with its query."},"detail":{"type":"string"},"code":{"type":"string","description":"Why the credential was refused: `unauthorized` (401) for a missing, invalid, expired or revoked credential; `scope_missing` (403) for one that lacks the scope this operation requires; `audience_restricted` (403) for one not granted for this dev-id; `authorization_unavailable` (503) when the credential could not be checked, so retry later.","enum":["unauthorized","scope_missing","audience_restricted","authorization_unavailable"]}}}},"parameters":{"ApiVersion":{"name":"X-Terra-Version","in":"header","required":false,"description":"The API version to serve this request in. Defaults to your account's pinned version; an account is pinned to the latest version on its first request.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}},"RequestId":{"description":"A UUID generated for this request, unique per request and never taken from the caller. Quote it to support to find the request.","schema":{"type":"string","format":"uuid"}}}},"paths":{"/api/v1/products/selection":{"put":{"operationId":"updateCatalogSelection","summary":"Set catalog selection","tags":["products"],"description":"Sets which products your catalogue reads return and which you can order, returning how many are enabled.\n\n- It replaces the whole selection: listed products become enabled, and every other product disabled.\n- With no selection saved, every product is enabled.\n- Products added to the catalogue after your last save are enabled until you save again.\n- Disabled products are left out of catalogue reads, and ordering one returns 403.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCatalogSelectionRequest"}}}},"parameters":[{"$ref":"#/components/parameters/ApiVersion"}],"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Selection saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCatalogSelectionResponse"}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Invalid request body. An unsupported `X-Terra-Version` also returns 400 with code `invalid_api_version`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"403":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"The credential lacks the scope this operation requires (code `scope_missing`) or is not granted for this dev-id (code `audience_restricted`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"500":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}}}}}}}
```

## Get products by type ID

> Lists the products of one product type that are sold in the environment's markets.\
> \
> \- Vantage sells in the UK and the US, with different products in each.\
> \- An environment lists every market until its markets are set. Testing environments choose theirs in the dashboard, and Terra sets production's.

```json
{"openapi":"3.2.0","info":{"title":"Terra Vantage API","version":"2026.11.11.1"},"tags":[{"name":"products","summary":"Products","description":"The test products and variants you can order, and the catalogue selection your environment offers."}],"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."},"DevIDHeader":{"type":"apiKey","in":"header","name":"dev-id","description":"Environment owned by the data token's customer and within its audience."}},"parameters":{"ApiVersion":{"name":"X-Terra-Version","in":"header","required":false,"description":"The API version to serve this request in. Defaults to your account's pinned version; an account is pinned to the latest version on its first request.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}},"RequestId":{"description":"A UUID generated for this request, unique per request and never taken from the caller. Quote it to support to find the request.","schema":{"type":"string","format":"uuid"}}},"schemas":{"Product":{"type":"object","required":["variants","availability"],"properties":{"enabled":{"type":"boolean","description":"Present only on ?show_all=true — the caller's per-product curation flag."},"availability":{"$ref":"#/components/schemas/Availability"},"base_price_cents":{"type":"integer","format":"int32"},"currency":{"$ref":"#/components/schemas/Currency"},"description":{"$ref":"#/components/schemas/RichText"},"id":{"type":"string","description":"Decimal string."},"images":{"description":"Every image of the product's variants, in display order.","type":"array","items":{"$ref":"#/components/schemas/Image"}},"name":{"type":"string"},"product_type_id":{"type":"string","description":"Decimal string."},"variants":{"type":"array","description":"The product's variants, on the same curation rules as GET /products/{id}/variants. Empty when the product has none.","items":{"$ref":"#/components/schemas/ProductVariant"}}}},"Availability":{"type":"string","description":"Whether the item can be ordered right now. `unknown` is served when the supplier has not stated availability.","enum":["unknown","in_stock","out_of_stock"]},"Currency":{"type":"string","description":"ISO 4217 alphabetic currency code. Omitted when the stored currency is not one of these. Versions before 2026-10-15 serve the ISO 4217 numeric code (840, 978, 826) instead.","enum":["USD","EUR","GBP"]},"RichText":{"description":"Rich text: a document tree with a node for every Markdown construct (CommonMark, without raw HTML, plus the GitHub Flavored Markdown table, strikethrough and task list extensions). Versions before 2026-10-29 serve the plain text instead: each block's text, blocks separated by a blank line.\n\nEvery node has a `type`. Every field listed for a node type is always present; a field with no value is `null`.\n\nWe'll add to this format over time, for example new node types such as block-level images, or new text styles. These additions don't come with a new API version, so make sure your code copes with things it hasn't seen before:\n\n- If a node has a field you don't know, ignore it.\n- If you come across a node `type` you don't know, skip it. If it has `children`, you can show those instead.\n- If `list_type` has a value you don't know, treat the list as unordered. If an `align` value is unknown, use the default alignment.\n\nChanges that could break existing code, such as removing or renaming a field or node type, only happen in a new API version.","type":"object","required":["type","children"],"properties":{"type":{"const":"root"},"children":{"type":"array","description":"The document's blocks in reading order. Empty when there is no text.","items":{"$ref":"#/components/schemas/RichTextBlock"}}}},"RichTextBlock":{"description":"A block-level node. Blocks sit in the document, a blockquote or a list item. Other types may be added: skip one you don't recognise.","anyOf":[{"$ref":"#/components/schemas/RichTextParagraph"},{"$ref":"#/components/schemas/RichTextHeading"},{"$ref":"#/components/schemas/RichTextBlockquote"},{"$ref":"#/components/schemas/RichTextList"},{"$ref":"#/components/schemas/RichTextCodeBlock"},{"$ref":"#/components/schemas/RichTextThematicBreak"},{"$ref":"#/components/schemas/RichTextTable"},{"$ref":"#/components/schemas/RichTextUnknownNode"}]},"RichTextParagraph":{"type":"object","required":["type","children"],"properties":{"type":{"const":"paragraph"},"children":{"type":"array","description":"Empty for an empty paragraph.","items":{"$ref":"#/components/schemas/RichTextInline"}}}},"RichTextInline":{"description":"An inline node. Inline nodes sit in a paragraph, heading or table cell. Other types may be added: skip one you don't recognise.","anyOf":[{"$ref":"#/components/schemas/RichTextText"},{"$ref":"#/components/schemas/RichTextLink"},{"$ref":"#/components/schemas/RichTextImage"},{"$ref":"#/components/schemas/RichTextLineBreak"},{"$ref":"#/components/schemas/RichTextUnknownNode"}]},"RichTextText":{"description":"A run of characters sharing one set of styles.","type":"object","required":["type","value","bold","italic","strikethrough","code"],"properties":{"type":{"const":"text"},"value":{"type":"string","minLength":1,"description":"The characters. A `\\n` is a soft line break."},"bold":{"type":"boolean"},"italic":{"type":"boolean"},"strikethrough":{"type":"boolean"},"code":{"type":"boolean","description":"Inline code."}}},"RichTextLink":{"type":"object","required":["type","url","title","children"],"properties":{"type":{"const":"link"},"url":{"type":"string","format":"uri","description":"An https, http or mailto URL."},"title":{"type":["string","null"]},"children":{"type":"array","description":"The linked content.","items":{"$ref":"#/components/schemas/RichTextLinkContent"}}}},"RichTextLinkContent":{"description":"An inline node inside a link: anything inline except another link. Other types may be added: skip one you don't recognise.","anyOf":[{"$ref":"#/components/schemas/RichTextText"},{"$ref":"#/components/schemas/RichTextImage"},{"$ref":"#/components/schemas/RichTextLineBreak"},{"$ref":"#/components/schemas/RichTextUnknownNode"}]},"RichTextImage":{"type":"object","required":["type","url","alt","title"],"properties":{"type":{"const":"image"},"url":{"type":"string","format":"uri","description":"An https URL."},"alt":{"type":"string","description":"Text describing the image; empty for a decorative image."},"title":{"type":["string","null"]}}},"RichTextLineBreak":{"description":"A hard line break.","type":"object","required":["type"],"properties":{"type":{"const":"line_break"}}},"RichTextUnknownNode":{"description":"A node type added after this description was written. Skip it, or, if it has a `children` array, render its children instead.","type":"object","required":["type"],"additionalProperties":true,"properties":{"type":{"type":"string","not":{"enum":["root","paragraph","heading","blockquote","list","list_item","code_block","thematic_break","table","table_row","table_cell","text","link","image","line_break"]}},"children":{"type":"array"}}},"RichTextHeading":{"type":"object","required":["type","level","children"],"properties":{"type":{"const":"heading"},"level":{"type":"integer","minimum":1,"maximum":6,"description":"1 is the most prominent, as in Markdown's `#` to `######`."},"children":{"type":"array","items":{"$ref":"#/components/schemas/RichTextInline"}}}},"RichTextBlockquote":{"type":"object","required":["type","children"],"properties":{"type":{"const":"blockquote"},"children":{"type":"array","items":{"$ref":"#/components/schemas/RichTextBlock"}}}},"RichTextList":{"type":"object","required":["type","list_type","start","children"],"properties":{"type":{"const":"list"},"list_type":{"type":"string","description":"`ordered` or `unordered`. Treat any other value as `unordered`."},"start":{"type":["integer","null"],"minimum":0,"description":"The number of an ordered list's first item; null for an unordered list."},"children":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/RichTextListItem"}}}},"RichTextListItem":{"type":"object","required":["type","checked","children"],"properties":{"type":{"const":"list_item"},"checked":{"type":["boolean","null"],"description":"Whether a task list item is done; null for an item that is not a task."},"children":{"type":"array","description":"The item's blocks, including any nested list.","items":{"$ref":"#/components/schemas/RichTextBlock"}}}},"RichTextCodeBlock":{"type":"object","required":["type","language","value"],"properties":{"type":{"const":"code_block"},"language":{"type":["string","null"],"description":"The language the code is in, e.g. json; null when none is stated."},"value":{"type":"string","description":"The code, verbatim, lines separated by `\\n`."}}},"RichTextThematicBreak":{"description":"A horizontal rule between sections.","type":"object","required":["type"],"properties":{"type":{"const":"thematic_break"}}},"RichTextTable":{"type":"object","required":["type","align","children"],"properties":{"type":{"const":"table"},"align":{"type":"array","description":"One entry per column: `left`, `center`, `right`, or null for the default. Treat any other value as null.","minItems":1,"items":{"type":["string","null"]}},"children":{"type":"array","description":"The rows. The first is the header row, and every row has one cell per column.","minItems":1,"items":{"$ref":"#/components/schemas/RichTextTableRow"}}}},"RichTextTableRow":{"type":"object","required":["type","header","children"],"properties":{"type":{"const":"table_row"},"header":{"type":"boolean","description":"True on the first row only."},"children":{"type":"array","items":{"$ref":"#/components/schemas/RichTextTableCell"}}}},"RichTextTableCell":{"type":"object","required":["type","children"],"properties":{"type":{"const":"table_cell"},"children":{"type":"array","items":{"$ref":"#/components/schemas/RichTextInline"}}}},"Image":{"type":"object","properties":{"alt_text":{"type":"string"},"display_order":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"},"id":{"type":"string","description":"Decimal string."},"product_id":{"type":"string","description":"Decimal string."},"url":{"type":"string"},"variant_id":{"type":"string","description":"Decimal string."},"width":{"type":"integer","format":"int32"}}},"ProductVariant":{"type":"object","required":["name","biomarkers","requires_activation","availability"],"properties":{"id":{"type":"string","description":"Decimal string."},"product_id":{"type":"string","description":"Decimal string."},"product_type_id":{"type":"string","description":"Decimal string."},"name":{"type":"string","description":"The variant's name, as the supplier states it."},"description":{"type":"string","description":"The supplier's blurb for this variant. Omitted when it states none."},"collection_method":{"$ref":"#/components/schemas/CollectionMethod"},"collection_visit":{"$ref":"#/components/schemas/CollectionVisit"},"requires_activation":{"type":"boolean","description":"Whether the kit has to be activated before the lab will process its sample. When true, call the kit activation endpoint as part of your flow; the sample is not processed without it."},"availability":{"$ref":"#/components/schemas/Availability"},"biomarkers":{"type":"array","description":"Biomarkers measured by this variant. Empty when the panel is not catalogued or could not be read.","items":{"$ref":"#/components/schemas/Biomarker"}},"reports":{"type":"array","description":"DNA tests only: the reports this variant's bundle includes. A DNA product's variants are report bundles; pick one at order time by its variant id. Omitted for other product types.","items":{"$ref":"#/components/schemas/DNAReport"}},"required_dna_details":{"type":"array","description":"DNA tests only: what an order for this variant must tell Terra about the end user, as JSON paths into the create-order request (recipient.gender_at_birth, or a key of dna). Empty when the variant needs nothing; omitted for other product types. An order missing any of them is rejected with 400 before payment. Non-exhaustive: new values may be added without a new API version.","items":{"type":"string","enum":["recipient.gender_at_birth","dna.health_measurements.height_cm","dna.health_measurements.weight_kg","dna.health_measurements.total_cholesterol_mg_dl","dna.health_measurements.systolic_blood_pressure_mmhg","dna.health_measurements.diastolic_blood_pressure_mmhg","dna.health_measurements.fasting_glucose_mg_dl","dna.health_measurements.hba1c_percent","dna.ancestry","dna.lifestyle","dna.medical_history","dna.eligibility","dna.consent"]}},"available_collection_types":{"type":"array","items":{"type":"string"}},"supported_ship_to_countries":{"type":"array","description":"ISO-3166 alpha-2 codes this test can be ordered in (AT_HOME shipping destination; for GO_TO_LAB, the requested lab country). Gate your address form on it - orders outside these countries are rejected with an unsupported_ship_to_country field error.","items":{"type":"string"}},"price_cents":{"type":"integer","format":"int32"},"currency":{"$ref":"#/components/schemas/Currency"},"images":{"description":"This variant's images, in display order. Omitted when it has none.","type":"array","items":{"$ref":"#/components/schemas/Image"}}}},"CollectionMethod":{"type":"string","description":"How the sample is taken. Omitted when the supplier states a method outside this vocabulary. New methods may be added; treat an unknown value as unstated.","enum":["finger_prick","venous_draw","automatic_capillary","cheek_swab"]},"CollectionVisit":{"type":"string","description":"The clinician visit the sample is taken at. Omitted for a self-collected kit. New visits may be added; treat an unknown value as a visit you cannot offer.","enum":["home_phlebotomy","clinic"]},"Biomarker":{"type":"object","description":"One measurement a kit includes.","required":["name","summary","description","source_url"],"properties":{"name":{"type":"string","description":"Human-readable biomarker name."},"code":{"type":"string","description":"The code the result bundle uses for this analyte."},"loinc":{"type":"string","description":"LOINC code for this analyte, when known."},"summary":{"type":["string","null"],"description":"A one-line, plain-language explanation of the biomarker, for people without a medical background, copied verbatim from the page at `source_url`. Null when no source explains it, as are `description` and `source_url`."},"description":{"description":"A fuller plain-language explanation, copied verbatim from the page at `source_url`, as rich text. Null exactly when `summary` is.","anyOf":[{"$ref":"#/components/schemas/RichText"},{"type":"null"}]},"source_url":{"type":["string","null"],"format":"uri","description":"The page `summary` and `description` are copied from, for crediting it where they are shown: the National Cancer Institute's Dictionary of Cancer Terms (cancer.gov) or MedlinePlus, U.S. National Library of Medicine (medlineplus.gov). Null exactly when `summary` is."}}},"DNAReport":{"type":"string","description":"A report category a DNA test's bundle includes; the same vocabulary as the DNA result's finding categories. Non-exhaustive: new categories may be added without a new API version.","enum":["carrier","monogenic","disease_risk","pgx","trait","longevity","ancestry"]},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}},"AuthenticationError":{"description":"Authentication error response (401)","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","status","title","type"]},"Refusal":{"description":"A credential refusal from Terra's edge, served as `application/problem+json` in every version. The HTTP status is not repeated in the body.","type":"object","required":["type","title","instance","detail","code"],"properties":{"type":{"type":"string"},"title":{"type":"string","description":"The HTTP status text, lowercased."},"instance":{"type":"string","description":"The request path, with its query."},"detail":{"type":"string"},"code":{"type":"string","description":"Why the credential was refused: `unauthorized` (401) for a missing, invalid, expired or revoked credential; `scope_missing` (403) for one that lacks the scope this operation requires; `audience_restricted` (403) for one not granted for this dev-id; `authorization_unavailable` (503) when the credential could not be checked, so retry later.","enum":["unauthorized","scope_missing","audience_restricted","authorization_unavailable"]}}}}},"paths":{"/api/v1/products/{id}":{"get":{"operationId":"getProductsByType","summary":"Get products by type ID","tags":["products"],"description":"Lists the products of one product type that are sold in the environment's markets.\n\n- Vantage sells in the UK and the US, with different products in each.\n- An environment lists every market until its markets are set. Testing environments choose theirs in the dashboard, and Terra sets production's.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"show_all","in":"query","required":false,"description":"When true, returns the full catalogue with each product's `enabled` flag, for curating your selection. Products outside the environment's markets are still left out. Defaults to false.","schema":{"type":"boolean","default":false}},{"name":"id","in":"path","description":"The product type's `id`, from `GET /api/v1/products`.","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Successfully retrieved products. An existing product type with no available products returns an empty array.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Invalid product type ID format. An unsupported `X-Terra-Version` also returns 400 with code `invalid_api_version`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Unauthorized - invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"403":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"The credential lacks the scope this operation requires (code `scope_missing`) or is not granted for this dev-id (code `audience_restricted`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"404":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Product type not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","instance","status","title","type"]}}}},"500":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}}}}}}}
```

## Get product variants by product ID

> Lists the variants of one product, the ways it can be ordered, such as different panel sizes or customisations.

```json
{"openapi":"3.2.0","info":{"title":"Terra Vantage API","version":"2026.11.11.1"},"tags":[{"name":"products","summary":"Products","description":"The test products and variants you can order, and the catalogue selection your environment offers."}],"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."},"DevIDHeader":{"type":"apiKey","in":"header","name":"dev-id","description":"Environment owned by the data token's customer and within its audience."}},"parameters":{"ApiVersion":{"name":"X-Terra-Version","in":"header","required":false,"description":"The API version to serve this request in. Defaults to your account's pinned version; an account is pinned to the latest version on its first request.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}},"RequestId":{"description":"A UUID generated for this request, unique per request and never taken from the caller. Quote it to support to find the request.","schema":{"type":"string","format":"uuid"}}},"schemas":{"ProductVariant":{"type":"object","required":["name","biomarkers","requires_activation","availability"],"properties":{"id":{"type":"string","description":"Decimal string."},"product_id":{"type":"string","description":"Decimal string."},"product_type_id":{"type":"string","description":"Decimal string."},"name":{"type":"string","description":"The variant's name, as the supplier states it."},"description":{"type":"string","description":"The supplier's blurb for this variant. Omitted when it states none."},"collection_method":{"$ref":"#/components/schemas/CollectionMethod"},"collection_visit":{"$ref":"#/components/schemas/CollectionVisit"},"requires_activation":{"type":"boolean","description":"Whether the kit has to be activated before the lab will process its sample. When true, call the kit activation endpoint as part of your flow; the sample is not processed without it."},"availability":{"$ref":"#/components/schemas/Availability"},"biomarkers":{"type":"array","description":"Biomarkers measured by this variant. Empty when the panel is not catalogued or could not be read.","items":{"$ref":"#/components/schemas/Biomarker"}},"reports":{"type":"array","description":"DNA tests only: the reports this variant's bundle includes. A DNA product's variants are report bundles; pick one at order time by its variant id. Omitted for other product types.","items":{"$ref":"#/components/schemas/DNAReport"}},"required_dna_details":{"type":"array","description":"DNA tests only: what an order for this variant must tell Terra about the end user, as JSON paths into the create-order request (recipient.gender_at_birth, or a key of dna). Empty when the variant needs nothing; omitted for other product types. An order missing any of them is rejected with 400 before payment. Non-exhaustive: new values may be added without a new API version.","items":{"type":"string","enum":["recipient.gender_at_birth","dna.health_measurements.height_cm","dna.health_measurements.weight_kg","dna.health_measurements.total_cholesterol_mg_dl","dna.health_measurements.systolic_blood_pressure_mmhg","dna.health_measurements.diastolic_blood_pressure_mmhg","dna.health_measurements.fasting_glucose_mg_dl","dna.health_measurements.hba1c_percent","dna.ancestry","dna.lifestyle","dna.medical_history","dna.eligibility","dna.consent"]}},"available_collection_types":{"type":"array","items":{"type":"string"}},"supported_ship_to_countries":{"type":"array","description":"ISO-3166 alpha-2 codes this test can be ordered in (AT_HOME shipping destination; for GO_TO_LAB, the requested lab country). Gate your address form on it - orders outside these countries are rejected with an unsupported_ship_to_country field error.","items":{"type":"string"}},"price_cents":{"type":"integer","format":"int32"},"currency":{"$ref":"#/components/schemas/Currency"},"images":{"description":"This variant's images, in display order. Omitted when it has none.","type":"array","items":{"$ref":"#/components/schemas/Image"}}}},"CollectionMethod":{"type":"string","description":"How the sample is taken. Omitted when the supplier states a method outside this vocabulary. New methods may be added; treat an unknown value as unstated.","enum":["finger_prick","venous_draw","automatic_capillary","cheek_swab"]},"CollectionVisit":{"type":"string","description":"The clinician visit the sample is taken at. Omitted for a self-collected kit. New visits may be added; treat an unknown value as a visit you cannot offer.","enum":["home_phlebotomy","clinic"]},"Availability":{"type":"string","description":"Whether the item can be ordered right now. `unknown` is served when the supplier has not stated availability.","enum":["unknown","in_stock","out_of_stock"]},"Biomarker":{"type":"object","description":"One measurement a kit includes.","required":["name","summary","description","source_url"],"properties":{"name":{"type":"string","description":"Human-readable biomarker name."},"code":{"type":"string","description":"The code the result bundle uses for this analyte."},"loinc":{"type":"string","description":"LOINC code for this analyte, when known."},"summary":{"type":["string","null"],"description":"A one-line, plain-language explanation of the biomarker, for people without a medical background, copied verbatim from the page at `source_url`. Null when no source explains it, as are `description` and `source_url`."},"description":{"description":"A fuller plain-language explanation, copied verbatim from the page at `source_url`, as rich text. Null exactly when `summary` is.","anyOf":[{"$ref":"#/components/schemas/RichText"},{"type":"null"}]},"source_url":{"type":["string","null"],"format":"uri","description":"The page `summary` and `description` are copied from, for crediting it where they are shown: the National Cancer Institute's Dictionary of Cancer Terms (cancer.gov) or MedlinePlus, U.S. National Library of Medicine (medlineplus.gov). Null exactly when `summary` is."}}},"RichText":{"description":"Rich text: a document tree with a node for every Markdown construct (CommonMark, without raw HTML, plus the GitHub Flavored Markdown table, strikethrough and task list extensions). Versions before 2026-10-29 serve the plain text instead: each block's text, blocks separated by a blank line.\n\nEvery node has a `type`. Every field listed for a node type is always present; a field with no value is `null`.\n\nWe'll add to this format over time, for example new node types such as block-level images, or new text styles. These additions don't come with a new API version, so make sure your code copes with things it hasn't seen before:\n\n- If a node has a field you don't know, ignore it.\n- If you come across a node `type` you don't know, skip it. If it has `children`, you can show those instead.\n- If `list_type` has a value you don't know, treat the list as unordered. If an `align` value is unknown, use the default alignment.\n\nChanges that could break existing code, such as removing or renaming a field or node type, only happen in a new API version.","type":"object","required":["type","children"],"properties":{"type":{"const":"root"},"children":{"type":"array","description":"The document's blocks in reading order. Empty when there is no text.","items":{"$ref":"#/components/schemas/RichTextBlock"}}}},"RichTextBlock":{"description":"A block-level node. Blocks sit in the document, a blockquote or a list item. Other types may be added: skip one you don't recognise.","anyOf":[{"$ref":"#/components/schemas/RichTextParagraph"},{"$ref":"#/components/schemas/RichTextHeading"},{"$ref":"#/components/schemas/RichTextBlockquote"},{"$ref":"#/components/schemas/RichTextList"},{"$ref":"#/components/schemas/RichTextCodeBlock"},{"$ref":"#/components/schemas/RichTextThematicBreak"},{"$ref":"#/components/schemas/RichTextTable"},{"$ref":"#/components/schemas/RichTextUnknownNode"}]},"RichTextParagraph":{"type":"object","required":["type","children"],"properties":{"type":{"const":"paragraph"},"children":{"type":"array","description":"Empty for an empty paragraph.","items":{"$ref":"#/components/schemas/RichTextInline"}}}},"RichTextInline":{"description":"An inline node. Inline nodes sit in a paragraph, heading or table cell. Other types may be added: skip one you don't recognise.","anyOf":[{"$ref":"#/components/schemas/RichTextText"},{"$ref":"#/components/schemas/RichTextLink"},{"$ref":"#/components/schemas/RichTextImage"},{"$ref":"#/components/schemas/RichTextLineBreak"},{"$ref":"#/components/schemas/RichTextUnknownNode"}]},"RichTextText":{"description":"A run of characters sharing one set of styles.","type":"object","required":["type","value","bold","italic","strikethrough","code"],"properties":{"type":{"const":"text"},"value":{"type":"string","minLength":1,"description":"The characters. A `\\n` is a soft line break."},"bold":{"type":"boolean"},"italic":{"type":"boolean"},"strikethrough":{"type":"boolean"},"code":{"type":"boolean","description":"Inline code."}}},"RichTextLink":{"type":"object","required":["type","url","title","children"],"properties":{"type":{"const":"link"},"url":{"type":"string","format":"uri","description":"An https, http or mailto URL."},"title":{"type":["string","null"]},"children":{"type":"array","description":"The linked content.","items":{"$ref":"#/components/schemas/RichTextLinkContent"}}}},"RichTextLinkContent":{"description":"An inline node inside a link: anything inline except another link. Other types may be added: skip one you don't recognise.","anyOf":[{"$ref":"#/components/schemas/RichTextText"},{"$ref":"#/components/schemas/RichTextImage"},{"$ref":"#/components/schemas/RichTextLineBreak"},{"$ref":"#/components/schemas/RichTextUnknownNode"}]},"RichTextImage":{"type":"object","required":["type","url","alt","title"],"properties":{"type":{"const":"image"},"url":{"type":"string","format":"uri","description":"An https URL."},"alt":{"type":"string","description":"Text describing the image; empty for a decorative image."},"title":{"type":["string","null"]}}},"RichTextLineBreak":{"description":"A hard line break.","type":"object","required":["type"],"properties":{"type":{"const":"line_break"}}},"RichTextUnknownNode":{"description":"A node type added after this description was written. Skip it, or, if it has a `children` array, render its children instead.","type":"object","required":["type"],"additionalProperties":true,"properties":{"type":{"type":"string","not":{"enum":["root","paragraph","heading","blockquote","list","list_item","code_block","thematic_break","table","table_row","table_cell","text","link","image","line_break"]}},"children":{"type":"array"}}},"RichTextHeading":{"type":"object","required":["type","level","children"],"properties":{"type":{"const":"heading"},"level":{"type":"integer","minimum":1,"maximum":6,"description":"1 is the most prominent, as in Markdown's `#` to `######`."},"children":{"type":"array","items":{"$ref":"#/components/schemas/RichTextInline"}}}},"RichTextBlockquote":{"type":"object","required":["type","children"],"properties":{"type":{"const":"blockquote"},"children":{"type":"array","items":{"$ref":"#/components/schemas/RichTextBlock"}}}},"RichTextList":{"type":"object","required":["type","list_type","start","children"],"properties":{"type":{"const":"list"},"list_type":{"type":"string","description":"`ordered` or `unordered`. Treat any other value as `unordered`."},"start":{"type":["integer","null"],"minimum":0,"description":"The number of an ordered list's first item; null for an unordered list."},"children":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/RichTextListItem"}}}},"RichTextListItem":{"type":"object","required":["type","checked","children"],"properties":{"type":{"const":"list_item"},"checked":{"type":["boolean","null"],"description":"Whether a task list item is done; null for an item that is not a task."},"children":{"type":"array","description":"The item's blocks, including any nested list.","items":{"$ref":"#/components/schemas/RichTextBlock"}}}},"RichTextCodeBlock":{"type":"object","required":["type","language","value"],"properties":{"type":{"const":"code_block"},"language":{"type":["string","null"],"description":"The language the code is in, e.g. json; null when none is stated."},"value":{"type":"string","description":"The code, verbatim, lines separated by `\\n`."}}},"RichTextThematicBreak":{"description":"A horizontal rule between sections.","type":"object","required":["type"],"properties":{"type":{"const":"thematic_break"}}},"RichTextTable":{"type":"object","required":["type","align","children"],"properties":{"type":{"const":"table"},"align":{"type":"array","description":"One entry per column: `left`, `center`, `right`, or null for the default. Treat any other value as null.","minItems":1,"items":{"type":["string","null"]}},"children":{"type":"array","description":"The rows. The first is the header row, and every row has one cell per column.","minItems":1,"items":{"$ref":"#/components/schemas/RichTextTableRow"}}}},"RichTextTableRow":{"type":"object","required":["type","header","children"],"properties":{"type":{"const":"table_row"},"header":{"type":"boolean","description":"True on the first row only."},"children":{"type":"array","items":{"$ref":"#/components/schemas/RichTextTableCell"}}}},"RichTextTableCell":{"type":"object","required":["type","children"],"properties":{"type":{"const":"table_cell"},"children":{"type":"array","items":{"$ref":"#/components/schemas/RichTextInline"}}}},"DNAReport":{"type":"string","description":"A report category a DNA test's bundle includes; the same vocabulary as the DNA result's finding categories. Non-exhaustive: new categories may be added without a new API version.","enum":["carrier","monogenic","disease_risk","pgx","trait","longevity","ancestry"]},"Currency":{"type":"string","description":"ISO 4217 alphabetic currency code. Omitted when the stored currency is not one of these. Versions before 2026-10-15 serve the ISO 4217 numeric code (840, 978, 826) instead.","enum":["USD","EUR","GBP"]},"Image":{"type":"object","properties":{"alt_text":{"type":"string"},"display_order":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"},"id":{"type":"string","description":"Decimal string."},"product_id":{"type":"string","description":"Decimal string."},"url":{"type":"string"},"variant_id":{"type":"string","description":"Decimal string."},"width":{"type":"integer","format":"int32"}}},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}},"AuthenticationError":{"description":"Authentication error response (401)","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","status","title","type"]},"Refusal":{"description":"A credential refusal from Terra's edge, served as `application/problem+json` in every version. The HTTP status is not repeated in the body.","type":"object","required":["type","title","instance","detail","code"],"properties":{"type":{"type":"string"},"title":{"type":"string","description":"The HTTP status text, lowercased."},"instance":{"type":"string","description":"The request path, with its query."},"detail":{"type":"string"},"code":{"type":"string","description":"Why the credential was refused: `unauthorized` (401) for a missing, invalid, expired or revoked credential; `scope_missing` (403) for one that lacks the scope this operation requires; `audience_restricted` (403) for one not granted for this dev-id; `authorization_unavailable` (503) when the credential could not be checked, so retry later.","enum":["unauthorized","scope_missing","audience_restricted","authorization_unavailable"]}}}}},"paths":{"/api/v1/products/{id}/variants":{"get":{"operationId":"listProductVariants","summary":"Get product variants by product ID","tags":["products"],"description":"Lists the variants of one product, the ways it can be ordered, such as different panel sizes or customisations.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"show_all","in":"query","required":false,"description":"When true, also returns variants of products disabled in your catalogue selection, for curation; those products still cannot be ordered. A product outside the environment's markets still returns 404. Defaults to false.","schema":{"type":"boolean","default":false}},{"name":"id","in":"path","description":"The product's `id`, from `GET /api/v1/products/{id}`.","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Successfully retrieved variants","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Invalid product ID format. An unsupported `X-Terra-Version` also returns 400 with code `invalid_api_version`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Unauthorized - invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"403":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"The credential lacks the scope this operation requires (code `scope_missing`) or is not granted for this dev-id (code `audience_restricted`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"404":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"No product variants were found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","instance","status","title","type"]}}}},"500":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}}}}}}}
```
