Ctrlk
Dashboard
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Orders

List orders

get

Keyset-paginated index of your orders, newest first. Pass the returned next_cursor to fetch the following page; absence of next_cursor means the last page.

Authorizations
AuthorizationstringRequired

Authenticate with your Terra API credentials: username = your Terra dev-id, password = your Terra API key — the same credentials used for every other Terra API. The header pair dev-id + x-api-key is also accepted. Suspended credentials receive 403; accounts without the Vantage entitlement receive 403 once entitlement enforcement is enabled.

Query parameters
limitinteger · min: 1 · max: 100OptionalDefault: 25
cursorstringOptional

order_id from the previous page's next_cursor

Example: 333410942627700736
sincestring · date-timeOptional

Only orders created at/after this RFC3339 timestamp.

missingbooleanOptional

true = only delivered/completed orders with at least one item whose results aren't in yet (the overview's "missing results" set).

Default: false
statusstringOptional

Filter by order status string (e.g. order.processing)

collection_typestring · enumOptionalPossible values:
Responses
200

One page of orders

application/json
next_cursorstringOptional

Pass as ?cursor= for the next page; absent on the last page.

Example: 333410942627700736
get/api/v1/orders
GET /api/v1/orders HTTP/1.1
Host: vantage.tryterra.co
Authorization: Basic username:password
Accept: */*

{
  "orders": [
    {
      "order_id": "333410942627700736",
      "client_order_reference_id": "ORDER-2024-001",
      "created_at": "2026-01-01T00:00:00.000Z",
      "collection_type": "AT_HOME",
      "order_status": "order.payment_processing",
      "total_cents": 5540,
      "currency": 840,
      "items": [
        {
          "order_item_id": "333410942627700737",
          "variant_id": "100011",
          "product_name": "General Health",
          "item_status": 1,
          "results_status": "results.awaiting_sample",
          "test_taker_id": "333410942627700738"
        }
      ]
    }
  ],
  "next_cursor": "333410942627700736"
}

Create a new order

post

Create a new blood, DNA, or device test order. Products that are disabled in your catalog cannot be ordered and are rejected with 403. Payment is authorized then captured as part of order creation; if authorization fails, nothing is created and a 402 is returned.

Authorizations
AuthorizationstringRequired

Authenticate with your Terra API credentials: username = your Terra dev-id, password = your Terra API key — the same credentials used for every other Terra API. The header pair dev-id + x-api-key is also accepted. Suspended credentials receive 403; accounts without the Vantage entitlement receive 403 once entitlement enforcement is enabled.

Header parameters
Idempotency-Keystring · max: 255Optional

Optional Stripe-style idempotency key. Replaying the same key with the same request body returns the original order without creating or charging again; the same key with a different body returns 409.

Example: a1b2c3d4-order-2024-001
Body

Request body for creating a new diagnostic test order

client_order_reference_idstring · min: 1 · max: 100Required

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.

Example: ORDER-2024-001
collection_typestring · enumRequired

Determines the required address field — shipping_address for AT_HOME, requested_lab_address for GO_TO_LAB.

Possible values:
Responses
201

Order created successfully

application/json

Response containing the created order details including tracking information

estimated_deliverystringOptionalExample: 2025-11-20
order_idstringRequiredExample: 123456789
order_statusstringOptional

Current fulfilment status in the REST order.* vocabulary. New orders start at order.payment_processing.

Example: order.payment_processing
recipient_idstringRequiredExample: 987654321
tracking_numberstringOptionalExample: TRK123456789GB
post/api/v1/orders
POST /api/v1/orders HTTP/1.1
Host: vantage.tryterra.co
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 820

{
  "client_order_reference_id": "ORDER-2024-001",
  "collection_type": "AT_HOME",
  "items": [
    {
      "quantity": 1,
      "variant_id": "555666777"
    }
  ],
  "recipient": {
    "date_of_birth": "1990-05-15",
    "email": "[email protected]",
    "first_name": "Sarah",
    "gender_at_birth": "female",
    "id": "123456789",
    "last_name": "Johnson",
    "phone_number": "+447911123456"
  },
  "requested_lab_address": {
    "address_line_1": "123 Baker Street",
    "address_line_2": "Flat 4B",
    "administrative_area": "Greater London",
    "city": "London",
    "country_code": "GB",
    "id": 987654321,
    "is_validated": true,
    "postal_code": "NW1 6XE"
  },
  "requested_lab": {
    "code": "T2O",
    "postal_code": "10001-6975"
  },
  "shipping_address": {
    "address_line_1": "123 Baker Street",
    "address_line_2": "Flat 4B",
    "administrative_area": "Greater London",
    "city": "London",
    "country_code": "GB",
    "id": 987654321,
    "is_validated": true,
    "postal_code": "NW1 6XE"
  }
}
{
  "confirmed_lab_address": {
    "address_line_1": "123 Baker Street",
    "address_line_2": "Flat 4B",
    "administrative_area": "Greater London",
    "city": "London",
    "country_code": "GB",
    "id": 987654321,
    "is_validated": true,
    "postal_code": "NW1 6XE"
  },
  "confirmed_lab": {
    "code": "T2O",
    "name": "Quest Diagnostics - NYC-26th St",
    "address": {
      "address_line_1": "123 Baker Street",
      "address_line_2": "Flat 4B",
      "administrative_area": "Greater London",
      "city": "London",
      "country_code": "GB",
      "id": 987654321,
      "is_validated": true,
      "postal_code": "NW1 6XE"
    },
    "phone": "212-555-0100",
    "hours": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "latitude": 40.7448,
    "longitude": -73.9938,
    "scheduling": true
  },
  "estimated_delivery": "2025-11-20",
  "order_id": "123456789",
  "order_items": [
    {
      "currency": 840,
      "item_status": 2,
      "lab_tracking_number": "LAB987654321",
      "order_id": "123456789",
      "order_item_id": "987654321",
      "price_per_item_cents": 9990,
      "product_type_id": "1",
      "test_taker_ids": [
        "333410942627700738"
      ],
      "supplier_item_id": "BXTWP00362",
      "quantity": 1,
      "results_status": "results.awaiting_sample",
      "variant_id": "555666777"
    }
  ],
  "order_status": "order.payment_processing",
  "recipient_id": "987654321",
  "tracking_number": "TRK123456789GB"
}

Get order by order ID

get

Returns complete order details including items, recipient, and status

Authorizations
AuthorizationstringRequired

Authenticate with your Terra API credentials: username = your Terra dev-id, password = your Terra API key — the same credentials used for every other Terra API. The header pair dev-id + x-api-key is also accepted. Suspended credentials receive 403; accounts without the Vantage entitlement receive 403 once entitlement enforcement is enabled.

Path parameters
orderIDinteger · min: 1Required

Order ID

Responses
200

Successfully retrieved order

application/json

Full order information including items, recipient, address, and financials

client_idstringRequiredExample: terra_client_abc123
client_order_reference_idstringRequiredExample: ORDER-2024-001
collection_typestringRequiredExample: AT_HOME
order_idstringRequiredExample: 123456789
order_statusstringOptional

Current fulfilment status in the REST order.* vocabulary.

Example: order.delivery_fulfilled
get/api/v1/orders/{orderID}
GET /api/v1/orders/{orderID} HTTP/1.1
Host: vantage.tryterra.co
Authorization: Basic username:password
Accept: */*

{
  "status_history": [
    {
      "status": "order.processing",
      "order_item_id": "333410942627700737",
      "changed_at": "2026-01-01T00:00:00.000Z",
      "escalation_level": "high",
      "acknowledgment_due_by": "2026-01-01T00:00:00.000Z"
    }
  ],
  "client_id": "terra_client_abc123",
  "client_order_reference_id": "ORDER-2024-001",
  "collection_type": "AT_HOME",
  "confirmed_lab_address": {
    "address_line_1": "123 Baker Street",
    "address_line_2": "Flat 4B",
    "administrative_area": "Greater London",
    "city": "London",
    "country_code": "GB",
    "id": 987654321,
    "is_validated": true,
    "postal_code": "NW1 6XE"
  },
  "items": [
    {
      "currency": 840,
      "item_status": 2,
      "lab_tracking_number": "LAB987654321",
      "order_id": "123456789",
      "order_item_id": "987654321",
      "price_per_item_cents": 9990,
      "product_type_id": "1",
      "test_taker_ids": [
        "333410942627700738"
      ],
      "supplier_item_id": "BXTWP00362",
      "quantity": 1,
      "results_status": "results.awaiting_sample",
      "variant_id": "555666777"
    }
  ],
  "order_financials": {
    "currency": 840,
    "discount_cents": 500,
    "total_cents": 10400
  },
  "order_id": "123456789",
  "order_status": "order.delivery_fulfilled",
  "recipient": {
    "date_of_birth": "1990-05-15",
    "email": "[email protected]",
    "first_name": "Sarah",
    "gender_at_birth": "female",
    "id": "123456789",
    "last_name": "Johnson",
    "phone_number": "+447911123456"
  },
  "requested_lab_address": {
    "address_line_1": "123 Baker Street",
    "address_line_2": "Flat 4B",
    "administrative_area": "Greater London",
    "city": "London",
    "country_code": "GB",
    "id": 987654321,
    "is_validated": true,
    "postal_code": "NW1 6XE"
  },
  "confirmed_lab": {
    "code": "T2O",
    "name": "Quest Diagnostics - NYC-26th St",
    "address": {
      "address_line_1": "123 Baker Street",
      "address_line_2": "Flat 4B",
      "administrative_area": "Greater London",
      "city": "London",
      "country_code": "GB",
      "id": 987654321,
      "is_validated": true,
      "postal_code": "NW1 6XE"
    },
    "phone": "212-555-0100",
    "hours": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "latitude": 40.7448,
    "longitude": -73.9938,
    "scheduling": true
  },
  "requested_lab": {
    "code": "T2O",
    "postal_code": "10001-6975"
  },
  "shipping_address": {
    "address_line_1": "123 Baker Street",
    "address_line_2": "Flat 4B",
    "administrative_area": "Greater London",
    "city": "London",
    "country_code": "GB",
    "id": 987654321,
    "is_validated": true,
    "postal_code": "NW1 6XE"
  }
}

Simulate an order lifecycle event (Testing environment only)

post

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.

Authorizations
AuthorizationstringRequired

Authenticate with your Terra API credentials: username = your Terra dev-id, password = your Terra API key — the same credentials used for every other Terra API. The header pair dev-id + x-api-key is also accepted. Suspended credentials receive 403; accounts without the Vantage entitlement receive 403 once entitlement enforcement is enabled.

Path parameters
orderIDstringRequiredExample: 333410942627700736
Body
eventstring · enumRequired

Lifecycle event to apply.

Possible values:
order_item_idstringOptional

Narrow a results event to one order item.

Example: 333410942627700737
Responses
200

Event applied

application/json
order_idstringRequiredExample: 333410942627700736
applied_eventstringRequiredExample: delivery_fulfilled
post/api/v1/orders/{orderID}/simulate
POST /api/v1/orders/{orderID}/simulate HTTP/1.1
Host: vantage.tryterra.co
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "event": "payment_complete",
  "order_item_id": "333410942627700737"
}
{
  "order_id": "333410942627700736",
  "applied_event": "delivery_fulfilled"
}
PreviousClientsNextProducts

Last updated

Was this helpful?