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

> Act on the prescription event that means trouble, prescription.cancelled, and on the order that has simply stopped sending events.

An order that has stopped moving looks exactly like an order that is simply early. This page is
the difference between the two: which prescription event means a human should look, what it
tells you, how to sweep for orders that have gone quiet, and what to hand support when the answer
is "escalate". It builds on *Order status and tracking*; the events are [signed webhooks](https://openloop.mintlify.site/events.md).

## What you'll do

**1. Act on the one trouble event: cancellation**

`prescription.cancelled` (`data.status` `cancelled`) is the only prescription event that means trouble.

**2. Treat a cancellation as the whole signal**

There is no structured reason field: `type` `prescription.cancelled` + `data.status` `cancelled` +
`data.timestamps.cancelled_at` is all you get.

**3. Read payment trouble from the billing events**

On-hold and unpaid states are not on prescription events, and a refund request appears only as
`prescription.refund_requested` at `2.0`. Read payment state from the billing events or the
payment pages.

**4. Run your own stale sweep**

There is no order list to poll. "No event for N days" on your own clock is the only stuck
signal you have.

**5. Escalate with the resource\_id and the last envelope id**

These are what make an escalation actionable when there is no API response to quote.

## Recipe · Spot the values that mean trouble

Only one prescription event means trouble: a cancellation. Every event carries the order's current
`data.status` (`created`, `ordered`, `shipped`, `delivered`, `cancelled`, `unknown`); check it on every
event you apply.

| What you see | What it means | What to do |
| - | - | - |
| `type` `prescription.cancelled`, or `data.status` `cancelled` | The order is cancelled | Handle it (next recipe) |
| A payment problem — on hold, unpaid | **Not carried on prescription events** (a refund request arrives as `prescription.refund_requested`, at `2.0` only) | Read it from the billing events (`invoice.paid`, `subscription.created`, `subscription.updated`) or `GET /v0.1/subscriptions` / `GET /v0.1/invoices`; see *Payment failure* and *Payments and checkout* |

**Payment trouble is not on prescription events.** There is no on-hold or payment-failure field on a
prescription payload. `prescription.invoiced`, `.paid` and `.refund_requested` arrive only on a `2.0`
subscription and say that billing moved, not why a payment failed. Detect payment
trouble from the `com.openloop.payments` events or the payment reads — see *Payment failure*.

`data.context` is a free-form `string → string` map whose keys are **not part of the versioned
contract**; do not route on a specific context key.

## Recipe · Handle a cancellation

`prescription.cancelled` sets `data.status` to `cancelled` and `data.timestamps.cancelled_at`. There is
**no structured cancellation-reason field** in the deployed contract — the event does not tell you why
the order was cancelled.

So a cancellation is a single fact: the order is cancelled, as of `cancelled_at`. Stop showing shipment
progress as the headline and show it as cancelled. If the patient did not ask for the cancellation,
escalate it with the ids below; the "why" has to come from your implementation contact, not the event.

Billing is a separate lifecycle. A cancelled order does not by itself cancel a subscription or
refund an invoice; that is *Cancel, pause and refund*. Refund and payment state live on the billing
events, not on the prescription event — see *Payment failure*.

## Recipe · Sweep for orders that have gone quiet

There is no order list on the partner surface, so you cannot ask OpenLoop which orders are stuck. Your own record of the events you
received is the sweep's input, and your own clock is its trigger.

Keep, per order (`data.resource_id`): the last `type`, the last `occurredAt`, and the time you
received it. On a schedule, flag every order whose last event is older than your threshold for that
stage and that has not reached a terminal state (`data.status` of `shipped` or `cancelled`):

| Last event | Quiet for longer than your threshold means |
| - | - |
| `prescription.created` | Raised but not yet sent to the pharmacy. Payment may be the holdup — check the billing events (see *Payment failure*) |
| `prescription.ordered` | At the pharmacy, not yet shipped |

The thresholds are yours; the contract gives none. Two cases the per-order sweep cannot
see, because no event exists to start the clock:

* **The order never appeared.** You took payment or submitted an intake and no
  `prescription.created` has arrived. Start that clock from your own submit time. No prescription
  event signals that a clinician declined to prescribe, so silence is all you will see.
* **Events stopped arriving for everyone.** If no event at all has reached your endpoint for longer
  than your usual traffic gap, suspect the delivery path before suspecting every order. The signature,
  retry and delivery policy are the standard webhook contract — see [Events](https://openloop.mintlify.site/events.md); a delivery that
  exhausts its retries is recorded as failed and is not re-sent automatically (an OpenLoop operator can
  re-drive it).

Before you escalate a quiet order, rule out your own side: confirm your endpoint returned `2xx` for
the events you did receive, and that an event was not dropped by your dedupe on the envelope `id` or
filed under the wrong patient (see the correlation rule on *Order status and tracking*).

## Recipe · Escalate

When an order is genuinely stuck, or cancelled without the patient asking, send your implementation
contact:

1. The **`data.resource_id`** from the event — your order key.
2. The envelope **`id`** and **`type`** of the last event you received for it, with its
   `occurredAt`.
3. The **`data.pharmacy`** identifier if it is set, labelled as the dispensing pharmacy.
4. What you expected to happen and by when, on your clock.

There is no API response here, so there is no `request_id` to quote; the envelope `id` plays that role.
Capture it from the event you actually stored, not from a later one.

## What comes back

| Attribute | Meaning | You key on it for |
| - | - | - |
| `data.resource_id` | The prescription (order) id | The record you sweep and escalate |
| `id` (envelope) | The event's idempotency key | Escalation; dedupe |
| `type` / `occurredAt` (envelope) | Which event, and when (UTC) | The stale sweep |
| `data.status` | `cancelled` is the terminal trouble value | Deciding whether to escalate |
| `data.timestamps.cancelled_at` | When the cancellation happened, UTC | Your timeline |
| `data.pharmacy` | The dispensing pharmacy identifier | A secondary reference in an escalation |

The full attribute set is on *Prescription events*.

## Gotchas

> [!WARNING]
>
> **Silence is not a status.** No event means nothing has been sent to you, not that nothing has
> happened. The stale sweep runs on your clock because there is no order read to confirm against.

> [!WARNING]
>
> **Payment state is not on a prescription event.** On-hold, unpaid and refunded are billing states,
> carried by the `com.openloop.payments` events (`invoice.paid`, `subscription.*`) and readable via
> `GET /v0.1/subscriptions` / `GET /v0.1/invoices` — never by a field on a prescription payload. The
> one exception is that a refund *request* arrives as `prescription.refund_requested`, at `2.0` only;
> it says a refund was asked for, not that it was paid out. See *Payment failure*.

> [!WARNING]
>
> **A cancellation carries no reason.** `prescription.cancelled` gives you `data.status` `cancelled` and
> `data.timestamps.cancelled_at` and nothing more — there is no structured reason field. If you need to
> know why, ask your implementation contact.

> [!NOTE]
>
> Webhook events cannot be exercised by the conformance runner, and this cookbook has not observed a
> cancellation on staging. The envelope, fields and status values are the deployed contract (see
> [Events](https://openloop.mintlify.site/events.md) and *Prescription events*); the routing guidance here is this cookbook's, not
> documented behaviour.

## Related

> [card] [Order status and tracking](https://openloop.mintlify.site/cookbook/order-status-and-tracking.md)
>
> The happy path this page interrupts: set-up, rendering status, dedupe and correlation

> [card] [Prescription events](https://openloop.mintlify.site/cookbook/prescription-events.md)
>
> Every attribute and value, the status enum and the timestamps

> [card] [Cancel, pause and refund](https://openloop.mintlify.site/cookbook/cancel-pause-refund.md)
>
> When the answer to a problem order is to stop billing for it or refund it

> [card] [Payment failure](https://openloop.mintlify.site/cookbook/payment-failure.md)
>
> When an order is on hold because the payment did not go through


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