Terra Vantage API

Order fulfilment status changed

Sent when an order's fulfilment status changes. data.status uses the same order.* vocabulary as REST reads of the order.

Deliveries carry X-Terra-Signature: t=<unix_seconds>,v1=<hex> where v1 = HMAC-SHA256(signing_secret, "<t>.<raw_body>") — verify against the raw body before trusting the payload — plus X-Terra-Trace-Id (the event_id). Delivery is at-least-once: dedupe on event_id. On network errors/408/429/5xx an event gets up to 5 HTTP attempts with exponential backoff (~1s, 2s, 4s, 8s) on first delivery, then single re-attempts with growing delays (5s doubling, capped at 10 minutes) for up to 10 deliveries in total — at most ~14 calls spread over ~30 minutes — before dead-lettering. Other 4xx responses are recorded as rejected and not retried at all.

Payload

event_typeconst: order.status_changedRequired

event_idstringRequired

Unique per event (64-bit id serialized as a string) — deduplicate on this. Equals the X-Terra-Trace-Id header.

Example: 249956485092777984

timestampintegerRequired

Unix seconds when the event was sent.

Example: 1763661470

Responses

200

Return any 2xx quickly to acknowledge receipt.

No content

Payload

{
  "event_type": "text",
  "event_id": "249956485092777984",
  "timestamp": 1763661470,
  "data": {
    "order_id": "333410942627700736",
    "status": "order.payment_processing",
    "tracking_number": "KnD3d5PMZyq5ulNcWkrq",
    "supplier_item_id": "249602021676720128"
  }
}

Order item results status changed

Sent when an order item's results status changes. data.results_status uses the results.* vocabulary shared with REST reads.

Signing, X-Terra-Trace-Id, at-least-once delivery, and retry semantics are identical to order.status_changed — see its description.

Payload

event_typeconst: order_item.results_status_changeRequired

event_idstringRequired

Unique per event (64-bit id serialized as a string) — deduplicate on this. Equals the X-Terra-Trace-Id header.

Example: 249958796259139584

timestampintegerRequired

Unix seconds when the event was sent.

Example: 1763662021

Responses

200

Return any 2xx quickly to acknowledge receipt.

No content

Payload

{
  "event_type": "text",
  "event_id": "249958796259139584",
  "timestamp": 1763662021,
  "data": {
    "order_id": "333410942627700736",
    "order_item_id": "333410942627700737",
    "variant_id": "100011",
    "results_status": "results.kit_activated",
    "test_taker": {
      "test_taker_id": "333410942627700738",
      "first_name": "text",
      "last_name": "text",
      "email": "text",
      "phone_number": "[phone]"
    },
    "escalation_level": "not_escalated",
    "acknowledgment_due_by": "2026-07-24T16:04:01Z",
    "failure_cause": "blood contaminated"
  }
}