> 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

## List all product types

> Returns all available diagnostic test categories (e.g., Blood Tests, DNA Tests)

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]}],"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.\n"}},"schemas":{"ProductType":{"type":"object","properties":{"description":{"type":"string"},"id":{"type":"integer","format":"int64"},"name":{"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"]},"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"}}}}},"paths":{"/api/v1/products":{"get":{"summary":"List all product types","tags":["products"],"description":"Returns all available diagnostic test categories (e.g., Blood Tests, DNA Tests)","responses":{"200":{"description":"Successfully retrieved product types","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}}}}},"401":{"description":"Unauthorized - invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```

## Set catalog selection

> Curate which products your own catalog reads return. Full-set write: listed products become enabled, every other product disabled. With no selection saved, everything is enabled; products added to the global catalog after your last save default to enabled until you save again. Disabled products are excluded from catalog reads and cannot be ordered (403).

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]}],"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.\n"}},"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"}}}}},"paths":{"/api/v1/products/selection":{"put":{"summary":"Set catalog selection","tags":["products"],"description":"Curate which products your own catalog reads return. Full-set write: listed products become enabled, every other product disabled. With no selection saved, everything is enabled; products added to the global catalog after your last save default to enabled until you save again. Disabled products are excluded from catalog reads and cannot be ordered (403).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCatalogSelectionRequest"}}}},"responses":{"200":{"description":"Selection saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCatalogSelectionResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```

## Get products by type ID

> Returns all products within a specific product type category

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]}],"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.\n"}},"schemas":{"Product":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Present only on ?show_all=true — the caller's per-product curation flag."},"availability":{"$ref":"#/components/schemas/AvailabilityStatus"},"base_price_cents":{"type":"integer","format":"int32"},"currency":{"$ref":"#/components/schemas/Currency"},"description":{"type":"string"},"id":{"type":"integer","format":"int64"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"model_descriptive_attrs":{"type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string"},"product_type_id":{"type":"integer","format":"int64"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}}}},"AvailabilityStatus":{"type":"integer","format":"int32","enum":[0,1,2]},"Currency":{"type":"integer","format":"int32","enum":[0,840,978,826]},"Image":{"type":"object","properties":{"alt_text":{"type":"string"},"display_order":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"},"id":{"type":"integer","format":"int64"},"product_id":{"type":"integer","format":"int64"},"url":{"type":"string"},"variant_id":{"type":"integer","format":"int64"},"width":{"type":"integer","format":"int32"}}},"ProductVariant":{"type":"object","properties":{"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"}},"currency":{"type":"integer","format":"int32"},"descriptive_attrs_override":{"type":"object","additionalProperties":{}},"id":{"type":"integer","format":"int64"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"price_cents":{"type":"integer","format":"int32"},"product_id":{"type":"integer","format":"int64"},"product_type_id":{"type":"integer","format":"int64"},"variant_availability":{"type":"integer","format":"int32"},"variant_defining_attrs":{"type":"object","additionalProperties":{}},"variant_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"]}}},"paths":{"/api/v1/products/{id}":{"get":{"summary":"Get products by type ID","tags":["products"],"description":"Returns all products within a specific product type category","parameters":[{"name":"show_all","in":"query","required":false,"description":"Return the full catalog with per-product enabled flags (curation view).","schema":{"type":"boolean","default":false}},{"name":"id","in":"path","description":"Product Type ID","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"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":{"description":"Invalid product type ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Unauthorized - invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"404":{"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":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```

## Get product variants by product ID

> Returns all available variants/options for a specific diagnostic test product (e.g., different panel sizes, customizations)

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]}],"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.\n"}},"schemas":{"ProductVariant":{"type":"object","properties":{"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"}},"currency":{"type":"integer","format":"int32"},"descriptive_attrs_override":{"type":"object","additionalProperties":{}},"id":{"type":"integer","format":"int64"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"price_cents":{"type":"integer","format":"int32"},"product_id":{"type":"integer","format":"int64"},"product_type_id":{"type":"integer","format":"int64"},"variant_availability":{"type":"integer","format":"int32"},"variant_defining_attrs":{"type":"object","additionalProperties":{}},"variant_name":{"type":"string"}}},"Image":{"type":"object","properties":{"alt_text":{"type":"string"},"display_order":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"},"id":{"type":"integer","format":"int64"},"product_id":{"type":"integer","format":"int64"},"url":{"type":"string"},"variant_id":{"type":"integer","format":"int64"},"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"]}}},"paths":{"/api/v1/products/{id}/variants":{"get":{"summary":"Get product variants by product ID","tags":["products"],"description":"Returns all available variants/options for a specific diagnostic test product (e.g., different panel sizes, customizations)","parameters":[{"name":"show_all","in":"query","required":false,"description":"Include variants of catalog-disabled products (curation view). Disabled products remain non-orderable regardless.","schema":{"type":"boolean","default":false}},{"name":"id","in":"path","description":"Product ID","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Successfully retrieved variants","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}}}}},"400":{"description":"Invalid product ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Unauthorized - invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"404":{"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":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```