> 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/orders.md).

# Orders

## List orders

> Keyset-paginated index of your orders, newest first. Pass the returned next\_cursor to fetch the following page; has\_more is false and next\_cursor null on the last page.

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"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."}},"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"]}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15"]}},"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":{"ListOrdersResponse":{"type":"object","description":"One page of orders, newest first. Versions before 2026-10-15 serve the items under `orders` instead of `data`, no `has_more`, and omit `next_cursor` on the last page.","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummary"}},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as ?cursor= for the next page; null on the last page."}}},"OrderSummary":{"type":"object","required":["order_id","created_at","collection_type","order_status","total_cents","items"],"properties":{"order_id":{"type":"string"},"client_order_reference_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"collection_type":{"type":"string","enum":["AT_HOME","GO_TO_LAB"]},"order_status":{"type":"string"},"total_cents":{"type":"integer"},"currency":{"$ref":"#/components/schemas/Currency"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummaryItem"}}}},"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"]},"OrderSummaryItem":{"type":"object","required":["order_item_id","variant_id","results_status"],"properties":{"order_item_id":{"type":"string"},"variant_id":{"type":"string"},"product_name":{"type":"string"},"item_status":{"$ref":"#/components/schemas/ItemStatus"},"results_status":{"type":"string","description":"`results.not_applicable` for a product that never produces a result (a supplement); it never changes and sends no results webhook."},"test_taker_id":{"type":"string"}}},"ItemStatus":{"type":"string","description":"The kit's shipping status. Omitted until the supplier reports one. Versions before 2026-10-15 serve the integer (1-4, 0 for none) instead.","enum":["pending_shipment","in_transit","delivery_attempted","delivered"]},"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/orders":{"get":{"operationId":"listOrders","summary":"List orders","tags":["orders"],"description":"Keyset-paginated index of your orders, newest first. Pass the returned next_cursor to fetch the following page; has_more is false and next_cursor null on the last page.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"limit","in":"query","required":false,"description":"Page size. Values above 100 are treated as 100.","schema":{"type":"integer","minimum":1,"default":25}},{"name":"cursor","in":"query","required":false,"description":"order_id from the previous page's next_cursor","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"Only orders created at/after this RFC3339 timestamp.","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"description":"Only orders created at/before this RFC3339 timestamp.","schema":{"type":"string","format":"date-time"}},{"name":"client_order_reference_id","in":"query","required":false,"description":"Only orders with exactly this client_order_reference_id. Use it to find an order you created when you did not keep its order_id.","schema":{"type":"string"}},{"name":"missing","in":"query","required":false,"description":"true = only delivered/completed orders with at least one item whose results aren't in yet (the overview's \"missing results\" set).","schema":{"type":"boolean","default":false}},{"name":"status","in":"query","required":false,"description":"Filter by order status string (e.g. order.processing)","schema":{"type":"string"}},{"name":"collection_type","in":"query","required":false,"schema":{"type":"string","enum":["AT_HOME","GO_TO_LAB"]}}],"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"One page of orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListOrdersResponse"}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Invalid pagination or filter parameters. 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"}}}},"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"}}}}}}}}}
```

## Create a new order

> Create a new blood, DNA, or device test order. Products that are disabled in your catalog cannot be ordered and are rejected with 403; so are products not offered in the environment you call, with code \`product\_unavailable\`. Payment is authorized then captured as part of order creation; if authorization fails, nothing is created and a 402 is returned.

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"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."}},"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"]}}},"schemas":{"CreateOrderRequest":{"description":"Request body for creating a new diagnostic test order","type":"object","properties":{"client_order_reference_id":{"description":"Your unique order identifier that you generate, used for tracking and reconciliation. Not deduplicated server-side — retrying a create with the same value produces a second order.","type":"string","minLength":1,"maxLength":100},"collection_type":{"type":"string","enum":["AT_HOME","GO_TO_LAB"],"description":"Determines the required address field — shipping_address for AT_HOME, requested_lab_address for GO_TO_LAB. A GO_TO_LAB variant whose collection_visit is `clinic` also needs shipping_address, where its kit is posted; any other GO_TO_LAB order must not send one."},"dna":{"$ref":"#/components/schemas/DNADetails"},"items":{"description":"Only need product_variant_id and quantity completely define what was ordered","type":"array","minItems":1,"items":{"$ref":"#/components/schemas/OrderItemRequest"}},"recipient":{"description":"Details of the person who ordered. Depending on the supplier recipient is not necessarily the test-taker. Although some suppliers enforce this constraint on us.","allOf":[{"$ref":"#/components/schemas/RecipientRequestDTO"}]},"requested_lab_address":{"$ref":"#/components/schemas/AddressDTO"},"requested_lab":{"$ref":"#/components/schemas/RequestedLab"},"shipping_address":{"$ref":"#/components/schemas/AddressDTO"}},"required":["client_order_reference_id","collection_type","items","recipient"]},"DNADetails":{"description":"What the DNA test needs to know about its end user, so the end user never deals with the supplier. Which details an order must carry depends on the variant ordered: each DNA variant lists them, by the JSON paths used here, in required_dna_details. A DNA order missing one, or with an invalid field, is rejected with 400 before payment, and invalid_fields names each field by its JSON path (for example dna.health_measurements.height_cm) with tag required, type, range, pair, enum, unexpected, words, item, rfc3339, future, max, iso_date or recipient_mismatch. Details the variant does not require may still be sent and are validated the same way. A person who answers true to an eligibility question is rejected with 400 and tag ineligible. Sex at birth is taken from recipient.gender_at_birth. Errors never echo the submitted values. Ignored when no item is a DNA product (product_type_id 2). Stored per DNA order item and never returned by the API.","type":"object","properties":{"health_measurements":{"$ref":"#/components/schemas/DNAHealthMeasurements"},"ancestry":{"$ref":"#/components/schemas/DNAAncestry"},"lifestyle":{"$ref":"#/components/schemas/DNALifestyle"},"medical_history":{"$ref":"#/components/schemas/DNAMedicalHistory"},"eligibility":{"$ref":"#/components/schemas/DNAEligibility"},"consent":{"$ref":"#/components/schemas/DNAConsent"}}},"DNAHealthMeasurements":{"description":"The end user's most recent measurements, in the units named by each key. Send a key when the variant's required_dna_details lists it; for a lab measurement, send null when the end user does not know the value (height and weight cannot be null). Ranges are the narrowest any DNA supplier accepts.","type":"object","properties":{"height_cm":{"description":"Height in centimetres (5 ft 6 in is 167.64).","type":"number","minimum":31,"maximum":272},"weight_kg":{"description":"Weight in kilograms.","type":"number","minimum":20,"maximum":600},"total_cholesterol_mg_dl":{"description":"Total cholesterol from the last blood test, mg/dL.","type":["number","null"],"exclusiveMinimum":0,"maximum":1000},"systolic_blood_pressure_mmhg":{"description":"Systolic blood pressure, mmHg. Null or left out exactly when diastolic is.","type":["integer","null"],"minimum":1,"maximum":999},"diastolic_blood_pressure_mmhg":{"description":"Diastolic blood pressure, mmHg. Null or left out exactly when systolic is.","type":["integer","null"],"minimum":1,"maximum":999},"fasting_glucose_mg_dl":{"description":"Fasting blood glucose, mg/dL.","type":["number","null"],"minimum":20,"maximum":500},"hba1c_percent":{"description":"HbA1c (A1C), percent.","type":["number","null"],"exclusiveMinimum":0,"maximum":50}}},"DNAAncestry":{"type":"object","required":["groups","ethnicity"],"properties":{"groups":{"description":"Every ancestry that applies. Duplicates are ignored.","type":"array","minItems":1,"items":{"type":"string","enum":["african_american","afro_caribbean","sub_saharan_african","african","alaska_native","central_asian","east_asian","hispanic","jewish_ashkenazi","jewish_sephardic_mizrahi_other","latino","middle_eastern_west_asian_north_african","native_american_indigenous_canadian","pacific_islander_oceanian","south_asian","southeast_asian","white_european","other"]}},"other":{"description":"Required when groups includes other, rejected otherwise. Letters, spaces and ' ( ) * + , - . / \" only, at most 100 characters.","type":"string","maxLength":100},"ethnicity":{"description":"Regional origin or ethnic roots, for example Persian. Letters, spaces and ' ( ) * + , - . / \" only, at most 100 characters.","type":"string","minLength":1,"maxLength":100}}},"DNALifestyle":{"type":"object","required":["smoking","alcohol"],"properties":{"smoking":{"$ref":"#/components/schemas/DNASmoking"},"alcohol":{"type":"string","enum":["never","couple_per_month","one_to_seven_per_week","eight_to_fourteen_per_week","more_than_fourteen_per_week"],"description":"How often the end user drinks alcohol (a couple of drinks per month, 1-7, 8-14 or more than 14 drinks per week)."}}},"DNASmoking":{"description":"years_since_quit is required for former and cigarettes_per_day for trying_to_quit and current; each is rejected for any other status.","type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["never","former","trying_to_quit","current"]},"years_since_quit":{"type":"integer","minimum":1,"maximum":100},"cigarettes_per_day":{"type":"integer","minimum":1,"maximum":100}}},"DNAMedicalHistory":{"type":"object","required":["diagnosed_conditions"],"properties":{"diagnosed_conditions":{"description":"Diseases or conditions the end user has or has had, in their own words; [] when none.","type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":200}}}},"DNAEligibility":{"description":"A DNA test cannot be run for a person who answers true to either question (donor DNA can be in the sample); such an order is rejected with tag ineligible.","type":"object","required":["bone_marrow_or_stem_cell_recipient","blood_transfusion_last_two_weeks"],"properties":{"bone_marrow_or_stem_cell_recipient":{"type":"boolean"},"blood_transfusion_last_two_weeks":{"type":"boolean"}}},"DNAConsent":{"description":"The end user's consent to the DNA test, collected in your app before ordering.","type":"object","required":["accepted_at","signature_name","date_of_birth","document_version"],"properties":{"accepted_at":{"description":"When the end user accepted, RFC 3339. Must not be later than the server time.","type":"string","format":"date-time"},"signature_name":{"description":"The full name the end user typed as their signature.","type":"string","minLength":1,"maxLength":200},"date_of_birth":{"description":"The date of birth the end user confirmed when signing. Must equal recipient.date_of_birth.","type":"string","format":"date"},"document_version":{"description":"The version of the consent document the end user was shown.","type":"string","minLength":1,"maxLength":100}}},"OrderItemRequest":{"description":"Individual product variant and quantity in an order","type":"object","properties":{"quantity":{"type":"integer","minimum":1,"maximum":100},"variant_id":{"type":["string","integer"],"minLength":1,"description":"The variant's id as a decimal string. A JSON number is also accepted."}},"required":["quantity","variant_id"]},"RecipientRequestDTO":{"description":"Recipient on an order-creation request. phone_number is a single E.164 string; the separate country_code field was removed and is silently ignored if still sent.","type":"object","properties":{"date_of_birth":{"type":"string"},"email":{"type":"string","maxLength":100},"first_name":{"type":"string","maxLength":50},"gender_at_birth":{"type":"string","enum":["male","female"]},"id":{"type":"string"},"last_name":{"type":"string","maxLength":50},"phone_number":{"type":"string","description":"Required, in E.164 format: a leading \"+\", the country calling code, then the national number (e.g. \"+447911123456\"). A bare national number or a separate country_code is rejected."}},"required":["date_of_birth","email","first_name","gender_at_birth","last_name","phone_number"]},"AddressDTO":{"description":"Physical address for shipping test kits","type":"object","properties":{"address_line_1":{"type":"string","minLength":1,"maxLength":100},"address_line_2":{"type":"string","maxLength":100},"administrative_area":{"type":"string","maxLength":50,"description":"State, province or county. For US addresses (`country_code` US) this must be the two-letter USPS state code, for example `TX`."},"city":{"type":"string","minLength":1,"maxLength":50},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g., \"GB\", \"US\")"},"id":{"type":"integer"},"is_validated":{"type":"boolean"},"postal_code":{"type":"string"}},"required":["address_line_1","administrative_area","city","country_code","postal_code"]},"RequestedLab":{"description":"GO_TO_LAB only: bind the order to a draw site chosen from GET /labs. code is the binding identity (row's code field); postal_code is a lookup hint (row's address.postal_code, ZIP+4 accepted - normalized to the 5-digit ZIP server-side; defaults to requested_lab_address.postal_code). Unknown codes are rejected with invalid_fields tag unknown_lab_code; if the lookup is temporarily unavailable the order is accepted unbound (confirmed_lab null).","type":"object","required":["code"],"properties":{"code":{"type":"string"},"postal_code":{"type":"string"}}},"CreateOrderResponse":{"description":"Response containing the created order details including tracking information","type":"object","properties":{"confirmed_lab_address":{"allOf":[{"$ref":"#/components/schemas/AddressDTO"}],"description":"For GO_TO_LAB orders: the bound draw site's address - the end user's selection when requested_lab was sent and verified, otherwise the nearest site to the requested lab address. Best-effort - null when resolution is unavailable; the requisition is typically accepted at any of the supplier network's sites."},"confirmed_lab":{"anyOf":[{"$ref":"#/components/schemas/ConfirmedLab"},{"type":"null"}]},"estimated_delivery":{"type":"string"},"order_id":{"type":"string"},"order_items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItemResponse"}},"order_status":{"type":"string","description":"Current fulfilment status in the REST `order.*` vocabulary. New orders start at `order.payment_processing`."},"recipient_id":{"type":"string"},"tracking_number":{"type":"string"}},"required":["order_id","recipient_id"]},"ConfirmedLab":{"description":"The draw site this order is bound to - a GET /labs row minus its request-relative distance field. Null when no binding exists (no selection and nearest-site resolution unavailable, or selection accepted unbound during a lookup outage).","type":"object","required":["code","name","address"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"address":{"$ref":"#/components/schemas/AddressDTO"},"phone":{"type":"string"},"hours":{"type":"object","additionalProperties":{"type":"string"}},"latitude":{"type":"number"},"longitude":{"type":"number"},"scheduling":{"type":"boolean"}}},"OrderItemResponse":{"description":"Individual test kit or product in the order","type":"object","properties":{"currency":{"$ref":"#/components/schemas/Currency"},"item_status":{"$ref":"#/components/schemas/ItemStatus"},"lab_tracking_number":{"type":"string"},"order_id":{"type":"string"},"order_item_id":{"type":"string"},"price_per_item_cents":{"type":"integer"},"product_type_id":{"type":"string"},"test_taker_ids":{"type":"array","description":"Test takers registered on this item (present once a kit is activated).","items":{"type":"string"}},"supplier_item_id":{"type":"string","description":"Supplier-side item identifier (kit ID once assigned). Recoverable here even if the webhook that carried it was missed."},"collection_visit":{"$ref":"#/components/schemas/OrderItemCollectionVisit"},"quantity":{"type":"integer"},"results_status":{"type":"string","description":"`results.not_applicable` for a product that never produces a result (a supplement); it never changes and sends no results webhook."},"variant_id":{"type":"string"}},"required":["variant_id","product_type_id","price_per_item_cents","quantity"]},"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"]},"ItemStatus":{"type":"string","description":"The kit's shipping status. Omitted until the supplier reports one. Versions before 2026-10-15 serve the integer (1-4, 0 for none) instead.","enum":["pending_shipment","in_transit","delivery_attempted","delivered"]},"OrderItemCollectionVisit":{"description":"The clinician visit Vantage arranged for this item's sample. Present only for a variant with a `collection_visit`.","type":"object","required":["type","status"],"properties":{"type":{"$ref":"#/components/schemas/CollectionVisit"},"status":{"type":"string","description":"Where arranging the visit stands. New statuses may be added; treat an unknown value as in progress.","enum":["booking","requested","booking_failed","awaiting_clinic_invite"]},"scheduling_url":{"type":"string","description":"Where the test-taker books the visit slot. Present once the provider has issued it, which can be shortly after the order is created; reading the order fetches it if it is still missing. Pass it on to the test-taker."}}},"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"]},"CreateOrderValidationError":{"description":"Validation error when creating an order","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"},"invalid_fields":{"type":"array","description":"Per-field validation errors","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"},"tag":{"type":"string"},"value":{"type":"string"}}}},"supported_ship_to_countries":{"type":"array","description":"Present when the order was rejected for an unsupported country (tag unsupported_ship_to_country) - the ISO-3166 alpha-2 codes this test can be ordered in.","items":{"type":"string"}}},"required":["detail","instance","status","title","type"]},"PaymentRequiredProblem":{"description":"402 returned by POST /orders when payment authorization fails. Nothing is created — no supplier order and no charge. The RFC 7807 problem fields plus a category the client can branch on. (Flat rather than an allOf over ProblemDetail: the conformance gate seals declared objects, and sealed allOf branches reject each other's properties.)","type":"object","required":["category","detail","status","title","type"],"properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"},"category":{"type":"string","description":"Failure class for programmatic branching."},"code":{"type":"string","description":"Why authorization failed. `payment_method_missing`: the account has no payment method on file; add one and retry. `card_declined`: the card issuer refused the charge; update or replace the card first. `payment_authorization_failed`: anything else, such as a temporary payment provider error; retrying may succeed. New values may be added, so treat an unknown code like `payment_authorization_failed`.","enum":["payment_method_missing","card_declined","payment_authorization_failed"]}}},"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"}}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15"]}},"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/orders":{"post":{"operationId":"createOrder","summary":"Create a new order","tags":["orders"],"description":"Create a new blood, DNA, or device test order. Products that are disabled in your catalog cannot be ordered and are rejected with 403; so are products not offered in the environment you call, with code `product_unavailable`. Payment is authorized then captured as part of order creation; if authorization fails, nothing is created and a 402 is returned.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional Stripe-style idempotency key. Replaying the same key with the same request body returns the original order with 200, without creating or charging again; the same key with a different body returns 409. If the original request failed before a supplier order was created or any payment was captured (for example a 402, a 403 catalogue rejection, or a 422 `order_not_approved`), the same key and body runs the request again. A key longer than 255 characters returns 400 with code `idempotency_key_too_long`. Versions before 2026-10-15 answer a replay with 201 and accept a longer key.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}},"description":"Order creation request","required":true},"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Idempotent replay: the Idempotency-Key and body match an order already created, which is returned unchanged. Nothing is created or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderResponse"}}}},"201":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Order created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderResponse"}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Bad request - invalid JSON or validation errors. An unsupported `X-Terra-Version` also returns 400 with code `invalid_api_version`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderValidationError"}}}},"402":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Payment authorization failed. Nothing was created — no supplier order and no charge. `code` says whether to add a payment method, replace a declined card, or retry. Retry with the same Idempotency-Key if you sent one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredProblem"}}}},"403":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"A requested product is not enabled in your catalog, or is not offered in this environment (code `product_unavailable`, for example a DNA product in Production). Nothing is created or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"The Idempotency-Key was already used with a different request body, a request with this key is still in progress, or the original request failed at a point where running it again could duplicate the order (retry with a new key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"The order was not approved for testing (code `order_not_approved`), for tests that need a clinician's authorisation before they can be ordered. Nothing was created and no payment was taken.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"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"}}}}}}}}}
```

## Get order by order ID

> Returns complete order details including items, recipient, and status

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"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."}},"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"]}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15"]}},"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":{"GetOrderResponse":{"description":"Full order information including items, recipient, address, and financials","type":"object","properties":{"status_history":{"type":"array","description":"Lifecycle timeline, newest first (order fulfilment + item results events).","items":{"type":"object","required":["status","changed_at"],"properties":{"status":{"type":"string"},"order_item_id":{"type":"string"},"changed_at":{"type":"string","format":"date-time"},"escalation_level":{"type":"string","description":"Present only on escalation_raised entries."},"acknowledgment_due_by":{"type":"string","format":"date-time","description":"Present only on escalation_raised entries."}}}},"client_id":{"type":"string"},"client_order_reference_id":{"type":"string"},"collection_type":{"type":"string"},"confirmed_lab_address":{"$ref":"#/components/schemas/AddressDTO"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItemResponse"}},"order_financials":{"$ref":"#/components/schemas/OrderFinancialDTO"},"order_id":{"type":"string"},"order_status":{"type":"string","description":"Current fulfilment status in the REST `order.*` vocabulary."},"recipient":{"$ref":"#/components/schemas/RecipientDTO"},"requested_lab_address":{"$ref":"#/components/schemas/AddressDTO"},"confirmed_lab":{"anyOf":[{"$ref":"#/components/schemas/ConfirmedLab"},{"type":"null"}]},"requested_lab":{"allOf":[{"$ref":"#/components/schemas/RequestedLab"}],"description":"Echo of the selection sent at create time - lets a retrieval-only consumer tell \"selected but unbound\" from \"no selection made\"."},"shipping_address":{"$ref":"#/components/schemas/AddressDTO"}},"required":["order_id","client_id","client_order_reference_id","recipient","shipping_address","items","order_financials","collection_type"]},"AddressDTO":{"description":"Physical address for shipping test kits","type":"object","properties":{"address_line_1":{"type":"string","minLength":1,"maxLength":100},"address_line_2":{"type":"string","maxLength":100},"administrative_area":{"type":"string","maxLength":50,"description":"State, province or county. For US addresses (`country_code` US) this must be the two-letter USPS state code, for example `TX`."},"city":{"type":"string","minLength":1,"maxLength":50},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g., \"GB\", \"US\")"},"id":{"type":"integer"},"is_validated":{"type":"boolean"},"postal_code":{"type":"string"}},"required":["address_line_1","administrative_area","city","country_code","postal_code"]},"OrderItemResponse":{"description":"Individual test kit or product in the order","type":"object","properties":{"currency":{"$ref":"#/components/schemas/Currency"},"item_status":{"$ref":"#/components/schemas/ItemStatus"},"lab_tracking_number":{"type":"string"},"order_id":{"type":"string"},"order_item_id":{"type":"string"},"price_per_item_cents":{"type":"integer"},"product_type_id":{"type":"string"},"test_taker_ids":{"type":"array","description":"Test takers registered on this item (present once a kit is activated).","items":{"type":"string"}},"supplier_item_id":{"type":"string","description":"Supplier-side item identifier (kit ID once assigned). Recoverable here even if the webhook that carried it was missed."},"collection_visit":{"$ref":"#/components/schemas/OrderItemCollectionVisit"},"quantity":{"type":"integer"},"results_status":{"type":"string","description":"`results.not_applicable` for a product that never produces a result (a supplement); it never changes and sends no results webhook."},"variant_id":{"type":"string"}},"required":["variant_id","product_type_id","price_per_item_cents","quantity"]},"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"]},"ItemStatus":{"type":"string","description":"The kit's shipping status. Omitted until the supplier reports one. Versions before 2026-10-15 serve the integer (1-4, 0 for none) instead.","enum":["pending_shipment","in_transit","delivery_attempted","delivered"]},"OrderItemCollectionVisit":{"description":"The clinician visit Vantage arranged for this item's sample. Present only for a variant with a `collection_visit`.","type":"object","required":["type","status"],"properties":{"type":{"$ref":"#/components/schemas/CollectionVisit"},"status":{"type":"string","description":"Where arranging the visit stands. New statuses may be added; treat an unknown value as in progress.","enum":["booking","requested","booking_failed","awaiting_clinic_invite"]},"scheduling_url":{"type":"string","description":"Where the test-taker books the visit slot. Present once the provider has issued it, which can be shortly after the order is created; reading the order fetches it if it is still missing. Pass it on to the test-taker."}}},"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"]},"OrderFinancialDTO":{"description":"Price breakdown including subtotal, tax, shipping, discounts","type":"object","properties":{"currency":{"$ref":"#/components/schemas/Currency"},"discount_cents":{"type":"integer","minimum":0},"total_cents":{"type":"integer","minimum":0}},"required":["total_cents"]},"RecipientDTO":{"description":"The recipient who will receive the test kit and may or may not be the test-taker (supplier-dependent)","type":"object","properties":{"date_of_birth":{"type":"string"},"email":{"type":"string","maxLength":100},"first_name":{"type":"string","maxLength":50},"gender_at_birth":{"type":"string","enum":["male","female"]},"id":{"type":"string"},"last_name":{"type":"string","maxLength":50},"phone_number":{"type":"string","description":"Full E.164 phone number as stored and dialed, including the \"+\" and country calling code (e.g. \"+447911123456\"). Leading zeros significant to the national number are preserved."}},"required":["date_of_birth","email","first_name","gender_at_birth","last_name","phone_number"]},"ConfirmedLab":{"description":"The draw site this order is bound to - a GET /labs row minus its request-relative distance field. Null when no binding exists (no selection and nearest-site resolution unavailable, or selection accepted unbound during a lookup outage).","type":"object","required":["code","name","address"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"address":{"$ref":"#/components/schemas/AddressDTO"},"phone":{"type":"string"},"hours":{"type":"object","additionalProperties":{"type":"string"}},"latitude":{"type":"number"},"longitude":{"type":"number"},"scheduling":{"type":"boolean"}}},"RequestedLab":{"description":"GO_TO_LAB only: bind the order to a draw site chosen from GET /labs. code is the binding identity (row's code field); postal_code is a lookup hint (row's address.postal_code, ZIP+4 accepted - normalized to the 5-digit ZIP server-side; defaults to requested_lab_address.postal_code). Unknown codes are rejected with invalid_fields tag unknown_lab_code; if the lookup is temporarily unavailable the order is accepted unbound (confirmed_lab null).","type":"object","required":["code"],"properties":{"code":{"type":"string"},"postal_code":{"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/orders/{orderID}":{"get":{"operationId":"getOrder","summary":"Get order by order ID","tags":["orders"],"description":"Returns complete order details including items, recipient, and status","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"orderID","in":"path","description":"Order 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 order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetOrderResponse"}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Invalid order 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"}}}},"404":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"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"}}}}}}}}}
```

## Simulate an order lifecycle event (Testing environment only)

> Drives one lifecycle event on your order exactly as a supplier update would — status history is recorded and the corresponding signed webhook is delivered to your registered destination. Only valid forward transitions are accepted. results\_ready also stores a sample result so the download and acknowledge flows work end to end. The production environment refuses with 403.

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"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."}},"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"]}}},"schemas":{"SimulateOrderRequest":{"type":"object","required":["event"],"properties":{"event":{"type":"string","description":"Lifecycle event to apply. `genome_processing`, `sample_reanalysis` and `reanalysed` apply to DNA order items only; `reanalysed` stores the next version of the item's result before its webhook fires.","enum":["payment_complete","payment_failed","processing","delayed","cancelled","delivery_fulfilled","completed","kit_activated","sample_processing_in_lab","sample_rejected","partial_results_ready","results_ready","lab_processing_error","escalation_raised","genome_processing","sample_reanalysis","reanalysed"]},"order_item_id":{"type":"string","description":"Narrow a results event to one order item."}}},"SimulateOrderResponse":{"type":"object","required":["order_id","applied_event"],"properties":{"order_id":{"type":"string"},"applied_event":{"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"}}},"SimulateTransitionProblem":{"description":"422 returned by the simulate endpoint when the requested event is not a valid forward transition from the current status. The RFC 7807 problem fields plus the two fields a client needs to recover without a GET round-trip. (Flat rather than an allOf over ProblemDetail: the conformance gate seals declared objects, and sealed allOf branches reject each other's properties.)","type":"object","required":["current_status","valid_events"],"properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"},"current_status":{"type":"string","description":"The status the rejected event was evaluated against."},"valid_events":{"type":"array","description":"Events accepted from current_status, sorted.","items":{"type":"string"}}}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15"]}},"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/orders/{orderID}/simulate":{"post":{"operationId":"simulateOrder","summary":"Simulate an order lifecycle event (Testing environment only)","tags":["orders"],"description":"Drives one lifecycle event on your order exactly as a supplier update would — status history is recorded and the corresponding signed webhook is delivered to your registered destination. Only valid forward transitions are accepted. results_ready also stores a sample result so the download and acknowledge flows work end to end. The production environment refuses with 403.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"orderID","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateOrderRequest"}}}},"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Event applied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateOrderResponse"}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Invalid order id, request body, order_item_id, or event. An unsupported `X-Terra-Version` also returns 400 with code `invalid_api_version`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"403":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Not available in the production environment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Order (or order item) not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Event is not a valid transition from the current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateTransitionProblem"}}}},"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"}}}}}}}}}
```