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), 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 at1.0. Each carries the same data shape and differs only in
data.status and which data.timestamps.* field it sets:
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 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).Recipe 4.5 · Parse an event
Every event is the full current state of one prescription. Verify the signature, look up your record bydata.resource_id, and drop the event if you have already applied its envelope id.
prescription.shipped (synthetic)
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.
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. Eachtimestamps.* 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 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 (Standard Webhooks,
whsec_secret); dedupe on the envelopeid; expect at-least-once with no ordering guarantee. - No payment state on the four
1.0events. They carry nopaid/invoicedfield.prescription.invoicedandprescription.paidarrive only on a2.0subscription; the payment itself is read from the billing events orGET /v0.1/subscriptions/GET /v0.1/invoices. - No cancellation reason field.
prescription.cancelledsetsstatustocancelledandtimestamps.cancelled_at; it does not carry a structured reason in the versioned contract. data.contextis free-form. Treat it as opaque; its keys are not versioned and may change without aneventVersionbump.patient_refis not guaranteed to be a/v0.1id. It is an opaque patient reference. Key onemr_patient_idwhen the event carries it.prescribed_product.codeis not a/v0.1id. It is a product code, not a/v0.1product 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).
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
Order status and tracking
How to use these events: set-up, rendering status, dedupe and correlation
Events
The envelope, the Standard Webhooks signature, and the delivery policy
Order exceptions
Cancellations and orders that have gone quiet

