Managing orders

Track orders after placement: fetch full order detail with status history, list and filter orders and results, and curate which products your catalog returns.

Webhooks are the primary way to follow an order (Webhooks), but the REST API gives you the full current state at any time - useful for reconciliation, support tooling, and recovering from missed webhooks.

Get one order

GET /api/v1/orders/{orderID} returns the complete order: items, recipient, addresses, financials, and a full status history.

curl 'https://vantage-sandbox.tryterra.co/api/v1/orders/251285377984405504' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'

{
  "order_id": "251285377984405504",
  "client_id": "terra_client_abc123",
  "client_order_reference_id": "TEST-ORDER-001",
  "collection_type": "AT_HOME",
  "order_status": "order.delivery_fulfilled",
  "recipient": {
    "id": "251285377984405505",
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone_number": "[phone]",
    "date_of_birth": "1995-10-10",
    "gender_at_birth": "male"
  },
  "shipping_address": {
    "address_line_1": "123 Market Street",
    "city": "San Francisco",
    "administrative_area": "CA",
    "country_code": "US",
    "postal_code": "94102"
  },
  "items": [
    {
      "order_id": "251285377984405504",
      "order_item_id": "251285377984405507",
      "variant_id": "100041",
      "product_type_id": "1",
      "price_per_item_cents": 7900,
      "quantity": 1,
      "currency": 840,
      "results_status": "results.kit_activated",
      "supplier_item_id": "249602021676720128",
      "test_taker_ids": ["257837964552478720"]
    }
  ],
  "order_financials": {
    "currency": 840,
    "total_cents": 7900
  },
  "status_history": [
    {
      "status": "results.kit_activated",
      "order_item_id": "251285377984405507",
      "changed_at": "2026-07-20T14:12:09Z"
    },
    {
      "status": "order.delivery_fulfilled",
      "changed_at": "2026-07-20T13:58:41Z"
    },
    {
      "status": "order.processing",
      "changed_at": "2026-07-20T13:55:02Z"
    }
  ]
}

Useful properties:

• status_history is the lifecycle timeline, newest first, mixing order-level fulfilment events and per-item results events. Escalation entries additionally carry escalation_level and acknowledgment_due_by.

• items[].supplier_item_id - the supplier-side kit ID, recoverable here even if you missed the webhook that carried it.

• items[].test_taker_ids - test takers registered on the item (present once a kit is activated); this is where to recover a test_taker_id you failed to capture from a webhook.

• Requesting an order that is not yours returns 404.

List orders

GET /api/v1/orders is a keyset-paginated index, newest first:

curl 'https://vantage-sandbox.tryterra.co/api/v1/orders?limit=25&status=order.processing' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'

Query parameters:

Parameter	Meaning
limit	Page size, 1-100 (default 25)
cursor	The next_cursor from the previous page
since	Only orders created at/after this RFC 3339 timestamp
status	Filter by order status string (e.g. order.processing)
collection_type	AT_HOME or GO_TO_LAB
missing	true = only delivered/completed orders that still have items without results - your "chase these up" set

The response is { "orders": [...], "next_cursor": "..." }; absence of next_cursor means the last page.

List results

GET /api/v1/results is the same pattern for result activity - one row per order item, including results_status, is_acknowledged, and test_taker_id:

curl 'https://vantage-sandbox.tryterra.co/api/v1/results?status=results.results_ready' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'

Use it to find results that are ready but not yet acknowledged (is_acknowledged: false).

Curating your catalog

By default, catalog reads return every product Terra offers you. If you only want to expose a subset to your application, save a selection:

curl --request PUT 'https://vantage-sandbox.tryterra.co/api/v1/products/selection' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "product_ids": ["10002", "10003"] }'

• This is a full-set write: listed products become enabled, every other product becomes 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 disappear from your normal catalog reads, and ordering them returns 403.

• To see the full catalog with per-product enabled flags (e.g. to build a curation UI), pass ?show_all=true to GET /api/v1/products/{id} or GET /api/v1/products/{id}/variants.