> ## Documentation Index
> Fetch the complete documentation index at: https://api.vitarelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Order Flow

> The end-to-end Vita Clinic lifecycle from patient creation through delivery.

# 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

<Steps>
  <Step title="Create the patient">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Submit the intake">
    ```bash theme={null}
    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"]
        }
      }'
    ```
  </Step>

  <Step title="Prescriber signs — intake.reviewed">
    A network prescriber reviews the intake. When they **sign the escript**,
    VitaRelay fires [`intake.reviewed`](/webhooks/events#intake-reviewed) with
    `status: "signed"`. Treat this as the "Rx cleared" signal.

    ```json theme={null}
    {
      "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"
    }
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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                              |
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Delivery">
    `order.delivered` fires on carrier-confirmed delivery. If the carrier reports
    a problem instead, `order.exception` fires with a `tracking_status`.
  </Step>
</Steps>

## Reading status

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

<CodeGroup>
  ```bash Webhooks theme={null}
  # Subscribe (via a VitaRelay admin) to:
  #   order.paid, order.shipped, order.delivered, order.exception
  ```

  ```bash Polling theme={null}
  curl https://vitarelay.com/api/public/v1/orders/0f1f2c9e-2f30-4a1b-8b1c-6f4e9a0c1d22 \
    -H "Authorization: Bearer vr_live_xxxx"
  ```
</CodeGroup>

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

## 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](/getting-started/sandbox).

<Warning>
  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.
</Warning>