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

# Managing orders

Webhooks are the primary way to follow an order ([Webhooks](/vantage-api-docs/documentation/webhooks.md)), 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.

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

```json
{
  "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": "john.smith@example.com",
    "phone_number": "+14155551234",
    "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:

```bash
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`:

```bash
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:

```bash
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`.