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

# Order status and tracking

> Receive the signed prescription webhook events, render order status and tracking from them, and match each event to your patient without an order read.

By the end of this page you will be able to show a patient where their order is: whether the pharmacy
has it, and the carrier tracking id once it ships. All of that reaches you as **signed prescription
webhook events** that OpenLoop POSTs to an endpoint you run. There is no order read to call.

## What you'll do

**1. Give OpenLoop an HTTPS endpoint**

Status arrives as prescription webhook events. You send the endpoint URL to your implementation
contact, who registers it and returns the signing secret; there is no self-serve registration.

**2. Verify every delivery**

Check the Standard Webhooks signature before trusting a payload — see [Events](https://openloop.mintlify.site/events.md).

**3. Render status from the payload**

`data.status` for the lifecycle stage, `data.timestamps.*` for the trail, `data.tracking_ref` and
`data.carrier` for tracking.

**4. Store the order, not the event**

Key on `data.resource_id`, drop repeats on the envelope `id`, and keep the latest state by `occurredAt`.

**5. Settle correlation before you build**

Key the patient on `data.emr_patient_id`, your `/v0.1` patient id, when the event carries it. For events without it, agree how the opaque `data.patient_ref` maps to your patients (Recipe 4.4).

## Why events, not a read

There is no partner order read; order status and tracking arrive only as prescription webhook events.
Nothing you call creates an order — an order is raised upstream, and the first `prescription.created`
event for it is the first time there is anything to show the patient. Paying and submitting an intake
come before that and have their own confirmations; see [Payments and checkout](https://openloop.mintlify.site/cookbook/payments-and-checkout.md)
and [Questionnaire workflow](https://openloop.mintlify.site/cookbook/questionnaire-workflow.md).

These are signed webhooks delivered by the same pipeline as every OpenLoop event: one envelope, one
signature scheme, one delivery policy, all documented in [Events](https://openloop.mintlify.site/events.md).

## Recipe 4.1 · Give OpenLoop your endpoint

Stand up an HTTPS endpoint that accepts a JSON `POST`, and send its URL to your implementation
contact. They register it, select the `prescription.*` events, and return your signing secret once.

Build the handler so that it:

* verifies the Standard Webhooks signature before trusting the body (see [Events](https://openloop.mintlify.site/events.md));
* returns a `2xx` quickly and does its work afterwards;
* tolerates the same event arriving twice (Recipe 4.3);
* tolerates events arriving out of order (Recipe 4.3).

## Recipe 4.2 · Read the lifecycle and render status

Four prescription lifecycle events are delivered at `1.0`, each carrying the order's current state. They differ by
`data.status` and which `data.timestamps.*` field they set:

| # | `type` | What it marks | `data.status` | Timestamp set |
| - | - | - | - | - |
| 1 | `prescription.created` | An order was raised | `created` | `timestamps.created_at` |
| 2 | `prescription.ordered` | It was sent to the pharmacy | `ordered` | `timestamps.ordered_at` |
| 3 | `prescription.shipped` | The pharmacy shipped it | `shipped` | `timestamps.shipped_at` |
| — | `prescription.cancelled` | The order was cancelled | `cancelled` | `timestamps.cancelled_at` |

`prescription.cancelled` is not a step every order passes through. [Order exceptions](https://openloop.mintlify.site/cookbook/order-exceptions.md)
covers it and orders that have gone quiet.

```json prescription.shipped (synthetic) theme={null}
{
  "id": "4b1e9c7a2f3d...e9f",
  "type": "prescription.shipped",
  "eventVersion": "1.0",
  "occurredAt": "2026-01-20T16:05:12.000Z",
  "data": {
    "resource_id": "rx_zz01",
    "patient_ref": "pat_zz01",
    "emr_patient_id": "b7d4e1a8-2c5f-4a9b-8e3d-6f1a4c7b0e92",
    "resource_organization_id": "org_zz01",
    "prescribed_product": { "code": "zzp-zzm-l1-w04", "display": "Compound ZZM 0.25mg" },
    "pharmacy": "phr_zz01",
    "status": "shipped",
    "timestamps": {
      "created_at": "2026-01-15T14:30:00.000Z",
      "ordered_at": "2026-01-16T09:12:00.000Z",
      "shipped_at": "2026-01-20T16:05:00.000Z"
    },
    "carrier": "usps",
    "tracking_ref": "ZZ0000000000000001",
    "occurred_at": "2026-01-20T16:05:12.000Z"
  }
}
```

### Render from `data.status`

Every event carries the prescription's current `data.status`. One way to turn it into a single
patient-facing line — the wording is yours:

| If `data.status` is | Show |
| - | - |
| `cancelled` | Cancelled |
| `shipped`, and `data.tracking_ref` is set | Shipped, with the tracking id |
| `shipped`, and `data.tracking_ref` is empty | Shipped, tracking to follow |
| `ordered` | At the pharmacy |
| `created` or `unknown` | Being prepared |

> [!NOTE]
>
> **Payment state is not on these events.** There is no paid/on-hold/refund status on a prescription
> event. Payment problems surface through the billing events and the payment flow — see
> [Payment failure](https://openloop.mintlify.site/cookbook/payment-failure.md) and [Payments and checkout](https://openloop.mintlify.site/cookbook/payments-and-checkout.md).

### Tracking

`data.tracking_ref` is the tracking number and `data.carrier` the carrier name. They are typically set
on `prescription.shipped`, but the contract does not pin them to that event, so render "shipped,
tracking to follow" when `tracking_ref` is empty. `data.timestamps.shipped_at` is a UTC ISO-8601
timestamp — show it as a datetime; it is a ship event, not a delivery estimate.

## Recipe 4.3 · Store the order: dedupe, order, accumulate

One order produces several events, and one prescription can have more than one order. Store one record per prescription and update it from each event.

1. **Key on `data.resource_id`.** It is the stable surrogate id of the prescription.
2. **Drop repeats on the envelope `id`.** Delivery is at-least-once, so the same event can arrive more than once; ignore an `id` you have already applied. (`id` is also the `webhook-id` header.)
3. **Keep the latest by `occurredAt`.** Deliveries are not ordered, so if an event's `occurredAt` is older than the one you already applied for that `resource_id`, record it but do not let it overwrite the status you show.

**The timestamps accumulate per order.** Each `data.timestamps.*` field is absent until its stage
happens, and from then on it is populated on every later event for that order:
`timestamps.ordered_at` set on a `prescription.shipped` event means the order was placed, even if
you never received `prescription.ordered`. A later order on the same prescription carries only its
own timestamps, so a second order's `prescription.cancelled` can arrive with no `ordered_at` or
`shipped_at` after the first order shipped. Merge each event's `timestamps` into the record, keeping
the first value set for each timestamp so a later order never overwrites it, and draw the progress
trail from the merged `timestamps`. A `prescription.cancelled` with neither `ordered_at` nor
`shipped_at` usually means that order was never placed: if the prescription already shipped, that
shipment still stands, so don't downgrade the status you show from shipped to cancelled on it.
Events can arrive out of order, so a `prescription.ordered` or `prescription.shipped` that arrives
after a cancel wins over it. An order with more than one fill sends each event once per fill, which
the merge absorbs. Keep `carrier` and `tracking_ref` from the order's first shipped event, since
they don't change after it, but take `pharmacy` from the latest event, since it changes when an
order is rerouted.

## Recipe 4.4 · Match the event to your patient

Settle this before you build, because the event does not always carry the identifiers you hold.

* **`data.emr_patient_id` is your `/v0.1` patient id**, the `id` that `GET /v0.1/patients/{id}` takes, when the event carries it. Key the event to your patient on it. It is omitted when the id isn't known, never `null`.
* **`data.patient_ref` is an opaque reference**, not guaranteed to be the `/v0.1` patient id, and the event carries no email and no phone. A patient you created with `POST /v0.1/patients` comes back from `GET /v0.1/patients/{id}` with no matching reference on it, so when the event has no `emr_patient_id`, how your tenant correlates it to a patient is agreed with your implementation contact when the endpoint is registered.
* **`data.prescribed_product.code` is a product code**, not a `/v0.1` product id or price id. Do not join it to your catalogue.
* **Nothing on the event points back at your intake.** It carries no `encounter_id` and no questionnaire response id.

> [!TIP]
>
> That a `/v0.1` patient read carries no `patient_ref` is locked by check `v01-patient-read-carries-only-partner-ids`.

## What comes back

Every event carries the same `data` shape. The full field list, with types and nullability, is on
[Prescription events](https://openloop.mintlify.site/cookbook/prescription-events.md). The ones this page uses:

| Field | Meaning | You key on it for |
| - | - | - |
| `id` (envelope) | The event's idempotency key | Dropping a repeated delivery |
| `occurredAt` (envelope) | When the event happened, UTC | Ordering events for the same order |
| `data.resource_id` | The prescription id | Your order record |
| `data.status` | Lifecycle stage | What you show |
| `data.timestamps.*` | When each milestone happened, UTC | The progress trail |
| `data.tracking_ref` / `data.carrier` | Tracking number / carrier | Tracking |
| `data.emr_patient_id` | Your `/v0.1` patient id, when known | Correlation (Recipe 4.4) |
| `data.patient_ref` | Opaque patient reference | Correlation without `emr_patient_id`, once agreed (Recipe 4.4) |

## Gotchas

> [!WARNING]
>
> **Do not build an order-polling loop.** There is no order read on the partner surface. Anything you
> show about an order after it is raised comes from the events you have stored.

> [!WARNING]
>
> **Do not treat `data.patient_ref` as your patient id.** It is an opaque reference. Key on
> `data.emr_patient_id` when the event carries it; matching `patient_ref` to a `/v0.1` patient is
> agreed when the endpoint is registered.

> [!WARNING]
>
> **Verify the signature.** Treat an unsigned or unverifiable `POST` as hostile — see [Events](https://openloop.mintlify.site/events.md)
> for the Standard Webhooks verification steps.

> [!NOTE]
>
> Webhook events cannot be exercised by the conformance runner. The envelope, signature and delivery
> policy are the deployed contract (see [Events](https://openloop.mintlify.site/events.md)); delivery to your endpoint is configured per
> customer by your implementation contact.

## Related

> [card] [Prescription events](https://openloop.mintlify.site/cookbook/prescription-events.md)
>
> The reference: every `data` field, its type, the status enum and the timestamps

> [card] [Events](https://openloop.mintlify.site/events.md)
>
> The envelope, the Standard Webhooks signature, and the delivery policy

> [card] [Order exceptions](https://openloop.mintlify.site/cookbook/order-exceptions.md)
>
> When this stage goes wrong: cancelled, or gone quiet


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.