Order Flow

This is the real lifecycle for a Vita Clinic integration: create the patient, submit the intake, wait for the prescriber to sign, create the order (which charges the card on file), then track fulfillment through webhooks. All calls use https://vitarelay.com/api/public/v1 with Authorization: Bearer vr_live_… (or vr_test_… for sandbox). All live ids are UUIDs.

The flow

Create the patient

curl -X POST https://vitarelay.com/api/public/v1/patients \
  -H "Authorization: Bearer vr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_patient_id": "ehr-patient-4821",
    "first_name": "Jane",
    "last_name": "Smith",
    "dob": "1985-04-12",
    "email": "jane.smith@example.com",
    "phone": "+18135550100"
  }'

Store the returned patient id against your local record. Re-sending the same external_patient_id with the same body returns the original patient.

Submit the intake

curl -X POST https://vitarelay.com/api/public/v1/intakes \
  -H "Authorization: Bearer vr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_intake_id": "ehr-intake-4821",
    "patient_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
    "category": "weight_management",
    "responses": {
      "height_in": 65,
      "weight_lb": 198,
      "goal": "weight loss",
      "current_medications": ["lisinopril"]
    }
  }'

Prescriber signs — intake.reviewed

A network prescriber reviews the intake. When they sign the escript, VitaRelay fires intake.reviewed with status: "signed". Treat this as the “Rx cleared” signal.

{
  "event": "intake.reviewed",
  "escript_id": "b93f0a7c-8d54-4b3a-9d20-1b4a7f2c5e10",
  "patient_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "status": "signed",
  "cart_ref": "clinic-cart-7781",
  "signed_at": "2026-08-04T14:58:02.117Z",
  "occurred_at": "2026-08-04T14:58:02.190Z"
}

Create the order

Creating an order runs the same pricing and economics as an in-app order and charges the clinic’s card on file synchronously.

curl -X POST https://vitarelay.com/api/public/v1/orders \
  -H "Authorization: Bearer vr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_order_id": "ehr-order-4821",
    "patient_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
    "items": [
      { "product_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "quantity": 1 }
    ],
    "shipping": {
      "line1": "123 Main St",
      "city": "Tampa",
      "state": "FL",
      "postal_code": "33601"
    }
  }'

Three outcomes:

Outcome	Meaning
Order created, payment status `paid`	Card on file charged successfully; `order.paid` fires
`402`	The charge was declined — fix the card on file and retry with a new `external_order_id`
Order created, `awaiting_payment` with `billing_dry_run`	Billing is in dry-run for the org; no charge was attempted

Fulfillment and shipping

VitaRelay routes the order to the fulfilling pharmacy. When it ships, order.shipped fires with tracking_number, tracking_carrier, and tracking_url.

Delivery

order.delivered fires on carrier-confirmed delivery. If the carrier reports a problem instead, order.exception fires with a tracking_status.

Reading status

There is no client-driven status endpoint — orders advance through real fulfillment events. Read current state either way:

# Subscribe (via a VitaRelay admin) to:
#   order.paid, order.shipped, order.delivered, order.exception

curl https://vitarelay.com/api/public/v1/orders/0f1f2c9e-2f30-4a1b-8b1c-6f4e9a0c1d22 \
  -H "Authorization: Bearer vr_live_xxxx"

Webhooks are the fast path; GET /orders/{id} is authoritative. Use webhooks to trigger work and the API to reconcile.

Sandbox rehearsal

With a vr_test_ key, the same three write calls create isolated sandbox objects that advance through a simulated lifecycle and fire the same events with "sandbox": true. No card is ever charged. See Sandbox.

Order creation is idempotent per clinic on the external_order_id body field — there is no Idempotency-Key header. Replaying the same external_order_id with the same body returns the original order (200 instead of 201); the same id with a different body returns 409 duplicate_request. Always send one.

Getting Started

Webhooks

Guides

Order Flow

Order Flow

The flow

Reading status

Sandbox rehearsal

​Order Flow

​The flow

​Reading status

​Sandbox rehearsal

Order Flow

The flow

Reading status

Sandbox rehearsal