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

# 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](/vantage-api/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,order.delayed' \
  -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                                                                   |
| `order`                     | `desc` for newest first (default), `asc` for oldest first                                                  |
| `since`, `until`            | Only orders created at/after, or at/before, this RFC 3339 timestamp                                        |
| `status`                    | Only orders in these statuses (e.g. `order.processing`); an unknown status returns `400`                   |
| `order_id`                  | Only these orders                                                                                          |
| `variant_id`                | Only orders with an item of one of these variants                                                          |
| `client_order_reference_id` | Only orders with exactly this reference                                                                    |
| `recipient_name`            | Only orders whose recipient's full name contains this text, ignoring case                                  |
| `recipient_email`           | Only orders whose recipient's email contains this text, ignoring case                                      |
| `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 |

Filters combine: an order must match every filter you send. `status`, `order_id` and `variant_id` take up to 100 values, repeated (`status=a&status=b`) or joined with commas, and match any of them. Send the same `order` and filters with every page's `cursor`.

The response is `{ "data": [...], "has_more": true, "next_cursor": "..." }`; `has_more` is `false` and `next_cursor` is `null` on 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&is_acknowledged=false' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'
```

Query parameters:

| Parameter                   | Meaning                                                                                              |
| --------------------------- | ---------------------------------------------------------------------------------------------------- |
| `limit`, `cursor`, `order`  | As for orders                                                                                        |
| `since`, `until`            | Only items updated at/after, or at/before, this RFC 3339 timestamp                                   |
| `status`                    | Only items in these results statuses (e.g. `results.results_ready`); an unknown status returns `400` |
| `is_acknowledged`           | `true` or `false`: only results you have, or have not, acknowledged                                  |
| `order_id`                  | Only items of these orders                                                                           |
| `variant_id`                | Only items of these variants                                                                         |
| `client_order_reference_id` | Only items of orders with exactly this reference                                                     |

`status`, `order_id` and `variant_id` take multiple values the same way as on orders. Use `status=results.results_ready&is_acknowledged=false` to find results that are ready but not yet acknowledged.

## 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`. The variants nested on each product in `GET /api/v1/products/{id}` follow the same rule.
* Curation applies within your environment's [markets](/vantage-api/core-concepts.md#markets): products outside them are left out even with `?show_all=true`, and a selection only enables products in your current markets, so changing markets later never finds products curated out.
