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

# Prescription events

> Reference for the four prescription lifecycle events, with a pointer to the four billing events: the signed envelope, the data payload, the status enum and the timestamps behind status and tracking.

This is the reference for the prescription webhook events that carry order status and tracking to you.
*Order status and tracking* teaches how to use them; this page lists exactly what they contain. They
are **signed webhooks**, delivered by the same pipeline, envelope and signature scheme as every other
OpenLoop event — see [Events](https://openloop.mintlify.site/events.md) for the envelope, the Standard Webhooks signature and the
delivery policy. Delivery is configured per customer: your OpenLoop implementation contact registers
your HTTPS endpoint and returns the signing secret.

## What you'll do

**1. Know the four lifecycle events**

`prescription.created`, `prescription.ordered`, `prescription.shipped`, `prescription.cancelled`,
at `1.0`. The four billing events arrive separately, at `2.0`.

**2. Read status from the payload**

`data.status` is the lifecycle stage; `data.timestamps.*` accumulate; `data.tracking_ref` and
`data.carrier` carry tracking once it ships.

**3. Verify and dedupe**

Verify the signature (see [Events](https://openloop.mintlify.site/events.md)), then dedupe on the envelope `id` and order by
`occurredAt`.

**4. Do not assume what is not written**

Payment state is not on these events; `data.context` keys are not part of the versioned contract.

## The events

Four lifecycle verbs are delivered at `1.0`. Each carries the same `data` shape and differs only in
`data.status` and which `data.timestamps.*` field it sets:

| `type` | What is new on this event | `data.status` | Timestamp set |
| - | - | - | - |
| `prescription.created` | The prescription exists | `created` | `timestamps.created_at` |
| `prescription.ordered` | It was sent to the pharmacy | `ordered` | `timestamps.ordered_at` |
| `prescription.shipped` | The pharmacy shipped it | `shipped` | `timestamps.shipped_at` (plus `carrier` / `tracking_ref`) |
| `prescription.cancelled` | It was cancelled | `cancelled` | `timestamps.cancelled_at` |

> [!NOTE]
>
> Four billing verbs, `prescription.invoiced`, `.paid`, `.refund_requested` and `.changed`, are
> delivered at `2.0` only, so a `1.0` subscription does not receive them; see
> [Events](https://openloop.mintlify.site/events.md#prescriptions) for their versions. `prescription.delivered` is not produced today.
> The payment itself is read from the billing events (`invoice.paid`, `subscription.*`) or
> synchronously via `GET /v0.1/subscriptions` and `GET /v0.1/invoices` (see
> [Payments and checkout](https://openloop.mintlify.site/cookbook/payments-and-checkout.md)).

## Recipe 4.5 · Parse an event

Every event is the full current state of one prescription. Verify the signature, look up your record
by `data.resource_id`, and drop the event if you have already applied its envelope `id`.

```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",
    "charting_note_id": "60000001",
    "occurred_at": "2026-01-20T16:05:12.000Z"
  }
}
```

### `data` attributes

The payload is `com.openloop.prescriptions` at `eventVersion` `1.0`. Names are snake\_case exactly as
below. **Required** means the key is always present; a **Nullable** key may carry `null`.

| Field | Type | Required | Nullable | Meaning |
| - | - | - | - | - |
| `resource_id` | string | Yes | No | Stable surrogate id of the prescription. Key your record on it. |
| `patient_ref` | string | Yes | No | Opaque reference to the patient; see [correlation](#correlating-to-your-patient). Not guaranteed to be a `/v0.1` patient id. |
| `emr_patient_id` | string | No | No | The patient's `/v0.1` id, the `id` that `GET /v0.1/patients/{id}` takes, when known; omitted otherwise, never `null`. See [correlation](#correlating-to-your-patient). |
| `resource_organization_id` | string | Yes | Yes | Owning organization id; `null` when not attributable to an org. |
| `prescribed_product` | object | Yes | Yes | The prescribed product, or `null`. |
| `prescribed_product.code` | string | Yes | No | Product code (present when `prescribed_product` is set). Not a `/v0.1` product or price id. |
| `prescribed_product.display` | string | No | No | Human-readable product name. |
| `pharmacy` | string | Yes | Yes | Dispensing pharmacy identifier; `null` when none assigned. |
| `status` | string | Yes | No | Lifecycle status; values below. |
| `timestamps` | object | Yes | No | Stage timestamp map; sub-fields are optional and accumulate. |
| `timestamps.created_at` | string | No | No | When the prescription was created (UTC, ISO-8601). |
| `timestamps.ordered_at` | string | No | No | When it was sent to the pharmacy. |
| `timestamps.shipped_at` | string | No | No | When it shipped. |
| `timestamps.delivered_at` | string | No | No | When it was delivered. Defined in the schema but not produced today. |
| `timestamps.cancelled_at` | string | No | No | When it was cancelled. |
| `carrier` | string | No | No | Shipping carrier name (typically set at/after shipment). |
| `tracking_ref` | string | No | No | Carrier tracking reference (typically set at/after shipment). |
| `charting_note_id` | string | No | No | Id of the clinician's charting note the prescription was ordered from; matches `data.resource_id` on that note's `charting.*` events. Omitted when the prescription was not ordered from a charting note; never `null`. See [Linking to the charting note](#linking-to-the-charting-note). |
| `context` | object | No | No | Free-form `string → string` map. Its keys are **not part of the versioned contract** — do not depend on specific keys. |
| `occurred_at` | string | Yes | No | When the event occurred (mirrors the envelope `occurredAt`). |

### `status` values

`data.status` is the canonical lifecycle stage, one of:

`created`, `ordered`, `shipped`, `delivered`, `cancelled`, `unknown`. `delivered` is defined in the
schema but no producer emits it today — the last status you will see is `shipped`.

Each event carries its matching value (e.g. `prescription.shipped` carries `shipped`). Render from
`data.status` and the populated `data.timestamps.*`, not from the event `type` string.

## Handle the dates

**They accumulate per order.** Each `timestamps.*` field is absent until its stage happens, then stays
populated on every later event for that order. `timestamps.ordered_at`, for example, first appears on
`prescription.ordered` and is still there on `prescription.shipped`, so within one order a missed
event does not lose a milestone. One prescription (`resource_id`) can have more than one order, and
each order's events carry only that order's timestamps, so the latest event does not always carry
the prescription's whole history. Merge the `timestamps` of every event for the `resource_id`,
keeping the first value set for each timestamp, and see the
[Events page](https://openloop.mintlify.site/events.md#prescriptions) for the cancel and out-of-order cases.

**One format.** Every timestamp — `occurredAt`, `occurred_at` and every `timestamps.*` — is a UTC
ISO-8601 datetime (`YYYY-MM-ddTHH:mm:ss.sssZ`). There is no date-only or local-timezone field.

Order events for the same `resource_id` by `occurredAt`, not by arrival. An event older than the one
you have already applied is history, not the current state.

## Linking to the charting note

`data.charting_note_id` is the clinician's charting note the prescription was ordered from. It
matches `data.resource_id` on that note's `charting.*` events, so key on it to tie the prescription
to the note. It is omitted, never `null`, when the prescription was not ordered from a charting
note.

## Gotchas

* **Signature and delivery are the standard contract.** Verify every delivery per [Events](https://openloop.mintlify.site/events.md) (Standard Webhooks, `whsec_` secret); dedupe on the envelope `id`; expect at-least-once with no ordering guarantee.
* **No payment state on the four `1.0` events.** They carry no `paid`/`invoiced` field. `prescription.invoiced` and `prescription.paid` arrive only on a `2.0` subscription; the payment itself is read from the billing events or `GET /v0.1/subscriptions` / `GET /v0.1/invoices`.
* **No cancellation reason field.** `prescription.cancelled` sets `status` to `cancelled` and `timestamps.cancelled_at`; it does not carry a structured reason in the versioned contract.
* **`data.context` is free-form.** Treat it as opaque; its keys are not versioned and may change without an `eventVersion` bump.
* **`patient_ref` is not guaranteed to be a `/v0.1` id.** It is an opaque patient reference. Key on `emr_patient_id` when the event carries it.
* **`prescribed_product.code` is not a `/v0.1` id.** It is a product code, not a `/v0.1` product or price id.
* **No event signals a declined prescription.** No prescription event, lifecycle or billing, says a clinician chose not to prescribe, so do not wait for one; handle that case on your own clock (see [Order exceptions](https://openloop.mintlify.site/cookbook/order-exceptions.md)).

## Correlating to your patient

`data.emr_patient_id` is the patient's `/v0.1` id, the `id` that `GET /v0.1/patients/{id}` takes.
When the event carries it, join the event to your patient on it. It is set whenever the id is known
and omitted otherwise, never `null`.

`data.patient_ref` is an opaque OpenLoop reference, not guaranteed to be the `/v0.1` patient id you
create with `POST /v0.1/patients`, and the event carries no email or phone to join on. When the event
has no `emr_patient_id`, how your tenant maps `patient_ref` to your own records is agreed with your
implementation contact when your endpoint is registered.

The claim that a `/v0.1` patient read carries no such reference is locked by check `v01-patient-read-carries-only-partner-ids` on *Order status and tracking* (Recipe 4.4); this page has no runner-checkable behaviour of its own.

## Related

> [card] [Order status and tracking](https://openloop.mintlify.site/cookbook/order-status-and-tracking.md)
>
> How to use these events: set-up, rendering status, dedupe and correlation

> [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)
>
> Cancellations and orders that have gone quiet


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