Skip to main content

​
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

1

Create the patient

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

Submit the intake

3

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. (If the order was placed first and is waiting on the prescription, it moves from submitted to processing once VitaRelay confirms the signed product and quantity match the order.)
4

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.
Three outcomes:
5

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.
6

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:
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.