Order Status History

Purpose

When you receive an order status webhook event (such as new_status_set_to_request), you can fetch the complete status history for an order at any time via the orderHistory field in the order detail endpoint.

This field provides affiliate integrations with a curated, chronological list of status changes without requiring v1 webhooks or making additional API calls to internal-only endpoints.

Accessing order status history

Retrieve the full order with its status history:

GET /orders/{order_id}

The response includes an orderHistory array:

{
  "id": "ord::example",
  "status": "started",
  "orderHistory": [
    {
      "status": "Started",
      "reason": null,
      "changedAt": "2026-07-15T10:00:00.000Z"
    },
    {
      "status": "Provider Review",
      "reason": "Provider review needed for clinical judgment",
      "changedAt": "2026-07-15T10:15:00.000Z"
    },
    {
      "status": "Order Processing",
      "reason": null,
      "changedAt": "2026-07-15T10:45:00.000Z"
    },
    {
      "status": "Affiliate Review",
      "reason": "Patient ineligible for insurance coverage",
      "changedAt": "2026-07-15T11:00:00.000Z"
    }
  ]
}

Field descriptions

Field	Type	Description
`status`	string	Human-readable affiliate-facing status label (e.g., `"Provider Review"`, `"Affiliate Review"`) — not the raw internal status slug from webhook payloads
`reason`	string \| null	Human-readable reason for the status change. May be null if no reason was recorded. Sanitized to exclude internal implementation details, system errors, and staff names (replaced with `"staff"`).
`changedAt`	ISO 8601 timestamp	UTC timestamp when the status change occurred (from the underlying event's `createdAt`)

Common status reasons

`Admin Review` (internal slug: `requires_admin_review`)

"An error occurred while processing the order" — indicates a system error occurred during order processing

`Affiliate Review` (internal slug: `requires_affiliate_review`)

"Patient ineligible for insurance coverage" — patient's insurance does not cover this order
"Patient age requirements not met" — patient's age falls outside the program's requirements
"Geographic restrictions apply" — order cannot be fulfilled in the patient's location
Other affiliate-specific disqualification criteria

Other statuses

reason is typically null for statuses like Started, Order Processing, Prescription Has Been Cancelled, etc., unless a specific note was recorded

Integration pattern

When you receive a webhook for an order status change:

Store the order_id from the webhook payload
After processing the webhook, optionally call GET /orders/{order_id} to retrieve the full order with status history
Use the orderHistory array to display or log the complete timeline for audit/reconciliation purposes

Availability

All orders have an orderHistory field in their affiliate view
History includes new_status_set_to_request events whose status maps to a known affiliate-facing label — statuses without a mapped label are excluded
Only public reasons are included — internal reasons and system errors are sanitized
The field is always present but may be an empty array for very new orders with no status changes yet

New Order Status Webhook — subscribe to receive status change notifications
Order Events Overview — all order-related webhook events
Webhooks v2 Overview — field coverage and sanitization policies