Orders

Create a new order

post

Create a new blood, DNA, or device test order

Body

application/json

Request body for creating a new diagnostic test order

client_order_reference_idstring · min: 1 · max: 100Required

Your unique order identifier that you generate (for idempotency and tracking)

Example: ORDER-2024-001

collection_typestringRequired

Responses

201

Order created successfully

application/json

400

Bad request - invalid JSON or validation errors

application/json

500

Internal server error

application/json

post

/orders

HTTPcURLJavaScriptPython

POST /orders HTTP/1.1
Host: vantage.tryterra.co
Content-Type: application/json
Accept: */*
Content-Length: 769

{
  "client_order_reference_id": "ORDER-2024-001",
  "collection_type": "text",
  "items": [
    {
      "quantity": 1,
      "variant_id": "555666777"
    }
  ],
  "recipient": {
    "country_code": 44,
    "date_of_birth": "1990-05-15",
    "email": "[email protected]",
    "first_name": "Sarah",
    "gender_at_birth": "f",
    "id": "123456789",
    "last_name": "Johnson",
    "phone_number": 447700900123
  },
  "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"
  },
  "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"
  },
  "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",
      "quantity": 1,
      "results_status": "awaiting_sample",
      "variant_id": "555666777"
    }
  ],
  "order_status": "pending_shipment",
  "recipient_id": "987654321",
  "tracking_number": "TRK123456789GB"
}

Get order by order ID

get

Returns complete order details including items, recipient, and status

Authorizations

BasicAuth

AuthorizationstringRequired

Path parameters

orderIDinteger · min: 1Required

Order ID

Responses

200

Successfully retrieved order

application/json

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

client_idstringOptionalExample: terra_client_abc123

client_order_reference_idstringOptionalExample: ORDER-2024-001

collection_typestringOptionalExample: AT_HOME

order_idstringOptionalExample: 123456789

order_statusstringOptionalExample: shipped

supplier_idstringOptionalExample: 1

400

Invalid order ID format

application/json

401

Unauthorized - invalid credentials

application/json

404

Order not found

application/json

500

Internal server error

application/json

get

/orders/{orderID}

HTTPcURLJavaScriptPython

GET /orders/{orderID} HTTP/1.1
Host: vantage.tryterra.co
Authorization: Basic username:password
Accept: */*

{
  "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",
      "quantity": 1,
      "results_status": "awaiting_sample",
      "variant_id": "555666777"
    }
  ],
  "order_financials": {
    "currency": 840,
    "discount_cents": 500,
    "total_cents": 10400
  },
  "order_id": "123456789",
  "order_status": "shipped",
  "recipient": {
    "country_code": 44,
    "date_of_birth": "1990-05-15",
    "email": "[email protected]",
    "first_name": "Sarah",
    "gender_at_birth": "f",
    "id": "123456789",
    "last_name": "Johnson",
    "phone_number": 447700900123
  },
  "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"
  },
  "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"
  },
  "supplier_id": "1"
}