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

# Refills

> Find the refill questionnaire, submit it, follow the approved refill through the prescription webhook events, and handle the commercial side of a refill.

Refills are the last leg of a staged rollout. The model is not what most integrators expect, and
getting it wrong means building an endpoint integration that does not exist.

## What you'll do

**1. Find the refill form**

A refill is a questionnaire. Hold its id per program in your own configuration.

**2. Submit it as a questionnaire response**

Same mechanics as intake — `answers` keyed by `link_id`, `subject` present, `status` completed.
The `201` carries an `encounter_id`.

**3. Watch for the prescription events**

A clinician reviews the refill. An approved refill arrives as a `prescription.created` event
for a new order at the webhook endpoint you registered with OpenLoop (by arrangement).

**4. Follow the shipment**

The same order's later events carry the carrier and tracking reference once it ships, exactly as
for a first fill.

## The model, stated plainly

**There is no dedicated refill endpoint.** A refill is a *questionnaire*. The patient completes a
refill form, you submit it as a questionnaire response exactly like an intake, a clinician reviews
it, and an approved refill produces a **new order**, which reaches you as prescription webhook
events (by arrangement) — not as something you read.

The published reference says so directly, on `POST /questionnaire-responses`:

> *"Refill requests work the same way: a refill is simply another questionnaire type, and the
> patient's completed response is the refill application."*

Neither the prescription, the order it produces, nor the encounter the submission created is a
partner-readable resource. What you hold is the `encounter_id` the submission returns; what you
receive afterwards is the prescription events for the new order. See *Prescription events*.

## The flow

```mermaid theme={null}
flowchart LR
    A["GET /v0.1/questionnaires<br/>Find the refill form"] --> B["POST /v0.1/questionnaire-responses<br/>Submit as the refill application"]
    B --> C["Clinical review"]
    C --> D["prescription.created event<br/>An approved refill arrives here (by arrangement)"]
```

## Recipe 6.1 · Find the refill form

`GET /v0.1/questionnaires?status=active` and select the refill form for the program. The same rule
as intake applies: **select by `status`, never by list position**.

```bash curl theme={null}
curl "https://api-staging.openloophealth.com/v0.1/questionnaires?status=active" \
  -H "authorization: Bearer $TOKEN"
```

```json Response theme={null}
{ "items": [ { "id": "<questionnaire id>", "title": "...", "status": "active", "items": [ ... ] } ],
  "request_id": "..." }
```

> [!WARNING]
>
> **Nothing in the API tells you which questionnaire is the refill form.** A questionnaire has an
> `id`, `title`, `status` and `items` — there is no type, purpose or program field. Today the only
> handles are the title and an id given to you out of band. Get the refill questionnaire ids from
> your OLH implementation contact and store them in your own configuration rather than pattern-matching
> titles, which will break when a title is edited.

> [!TIP]
>
> Locked by check `nothing-marks-a-questionnaire-as-a-refill-form`.

## Recipe 6.2 · Submit it as a questionnaire response

Identical mechanics to intake — see *Integration flow*. `answers` is an object keyed by `link_id`,
`subject` must be present with the patient, and `status` must be `"completed"`. The `201` returns
the response id and the `encounter_id` the platform created for this refill.

```bash curl theme={null}
curl -X POST https://api-staging.openloophealth.com/v0.1/questionnaire-responses \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "questionnaire_id": "<the refill questionnaire id>",
    "subject": { "id": "<patient id>", "type": "Patient" },
    "status": "completed",
    "answers": { "q1": { "value_string": "No new symptoms" } }
  }'
```

```json Response theme={null}
{ "data": { "id": "<response id>", "encounter_id": "<encounter id>" }, "request_id": "..." }
```

A completed submission creates the encounter and returns its `encounter_id` (verified on staging,
2026-10-05). Store it with your record of the refill application. The encounter itself is not
partner-readable, so the `201` is your confirmation that the submission landed; the id is the key
that brings back the clinician's note on it, if one is charted (staging only for now; see
[Encounter notes](https://openloop.mintlify.site/cookbook/encounter-notes.md)).

Both of intake's silent failures apply here unchanged — see Gotchas.

> [!TIP]
>
> Locked by check `refill-submission-creates-an-encounter`.

## Recipe 6.3 · Watch for the prescription events

The clinician's decision is not exposed to you as a resource, and there is no order read. An
approved refill reaches you as a `prescription.created` event for a **new** order, delivered to
the HTTPS endpoint you gave OpenLoop when the feature was set up (by arrangement; there is no
self-serve registration). These are **signed webhooks**; the signature and delivery contract is on
*Events*. The rest of the lifecycle follows as `prescription.ordered`, `prescription.shipped` and,
where it applies, `prescription.cancelled` — four lifecycle events in all, at `1.0`. The full attribute set is on
*Prescription events*.

```json prescription.created (synthetic) theme={null}
{
  "id": "4b1e9c7a2f3d...e9f",
  "type": "prescription.created",
  "eventVersion": "1.0",
  "occurredAt": "2026-01-15T14:30:00.000Z",
  "data": {
    "resource_id": "rx_zz01",
    "patient_ref": "pat_zz01",
    "emr_patient_id": "b7d4e1a8-2c5f-4a9b-8e3d-6f1a4c7b0e92",
    "prescribed_product": { "code": "zzp-zzm-l1-w04", "display": "Compound ZZM 0.25mg" },
    "status": "created",
    "timestamps": { "created_at": "2026-01-15T14:30:00.000Z" },
    "carrier": null,
    "tracking_ref": null,
    "occurred_at": "2026-01-15T14:30:00.000Z"
  }
}
```

An approved refill arrives with its own `data.resource_id`; it does not mutate the previous order, so
key your records on the new `resource_id` rather than expecting an update in place. Every event for an
order carries the same `data` shape, and each `data.timestamps.*` field is absent until its stage
happens, then stays populated on every later event for that order.

Matching the event to your patient and your refill is the part to settle before you build:

* **`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 or phone. If your patients exist only through `POST /v0.1/patients`, how an
  event without `emr_patient_id` is correlated to them 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.
* **Nothing on the event points back at your submission.** It carries no `encounter_id` and no
  questionnaire response id. To tell the refill order from the first fill, compare
  `data.timestamps.created_at` with the time you submitted the refill response, and match on the
  product.
* **No field marks an order as a refill.** An approved refill is a plain `prescription.created` for a
  new `resource_id`; there is no fill-number or refill flag in the contract, so distinguish it in
  your own records (see below).

Order state is `data.status`, one of `created`, `ordered`, `shipped`, `delivered`, `cancelled` or
`unknown`. Payment state is **not** on these events — read it from the billing events or
`GET /v0.1/subscriptions` / `GET /v0.1/invoices`. See *Order status and tracking*.

> [!NOTE]
>
> Webhook events cannot be exercised by the conformance runner, so nothing in this recipe is locked
> by a check. The event names and attributes are from the deployed webhook contract (see *Events* and
> *Prescription events*), not observed on staging by this cookbook.

## Recipe 6.4 · Follow the shipment

The same order's later events carry the shipment. `prescription.shipped` brings `data.tracking_ref`
and `data.carrier`, and sets `data.timestamps.shipped_at` — a UTC ISO-8601 datetime, not a delivery
estimate. Key on `data.resource_id`.

There is no read to sweep for stalled refills. Keep the last `data.status` and `occurredAt` you
received per `resource_id` in your own store, and age that: an order whose last event is
`prescription.ordered` and has not reached `prescription.shipped` is the one to raise with your
implementation contact, quoting the `resource_id` and the envelope `id`.

## What comes back

| Field | Meaning | You key on it for |
| - | - | - |
| `items[].id` (questionnaires) | The refill form's id | Your configuration — nothing in the API marks a form as the refill form |
| `data.id` (response) | The refill application you just submitted | Your own record of the application |
| `data.encounter_id` | The encounter the platform created from it | Your own record, and the `encounter_id` filter on the questionnaire-response list if a note is charted against it |
| `data.resource_id` | The order; a new one per approved refill | Your record of the refill — a refill never mutates an earlier order |
| `type` / `occurredAt` / `id` (envelope) | Which lifecycle event this is, when, and its unique id | Ordering events by `occurredAt` and de-duplicating on `id` |
| `data.emr_patient_id` | Your `/v0.1` patient id, when known | Correlation |
| `data.patient_ref` | An opaque reference, not guaranteed to be the `/v0.1` patient id | Correlation without `emr_patient_id`, as agreed when the endpoint is registered |
| `data.prescribed_product.code` / `.display` | Product code and human-readable name | Matching the order to the refill you submitted |
| `data.status` | Order lifecycle state (`created`…`cancelled`); payment state is not here | Whether the refill is moving; read payment from the billing events |
| `data.tracking_ref` / `data.carrier` | The shipment's tracking reference and carrier | Showing the patient where the refill is |
| `request_id` | Present on every API response, success or failure | Support, when a submission misbehaves |

## The commercial side

A refill that is part of a subscription renews through the subscription, not through a new
checkout. See *Upsell and cross-sell* for subscription lookup (keyed by **email**, not patient id),
pausing, and the customer portal. Each renewal produces an invoice on
`GET /v0.1/subscriptions/{provider_subscription_id}/invoices`, which is how you reconcile a refill
shipment against what the patient was charged.

## Gotchas

> [!WARNING]
>
> **Both intake silent failures apply here.** Everything from the intake page applies to a refill
> submission, including both silent failures: `status: "in-progress"` or a missing `subject` returns
> `201` and quietly does nothing useful. See *Integration flow*.

> [!NOTE]
>
> Submitting as `completed` with a patient subject can trigger automation configured for your
> program — survey observations, lab requisitions — so a refill submission is not inert.

> [!NOTE]
>
> The API will not distinguish a refill response from an intake response for you, and no
> prescription event tells you which response its order came from. Decide how you will tell them apart in your own
> records — response id, submission time, medication — before you build.

> [!NOTE]
>
> **A declined refill leaves no trace you can read.** No `prescription.created` event follows, and
> the encounter is not partner-readable. If the patient needs to know, that conversation happens through the care
> team, not through a status you can poll. See *Not eligible*.

## Before you build

1. You have the refill questionnaire id for each program, in your own configuration
2. Your webhook endpoint is registered with OpenLoop, its delivery mechanics (signature, retries)
   are confirmed, and you have agreed how a `data.patient_ref` (an opaque reference) maps to your patients
   on events that carry no `data.emr_patient_id`
3. You have decided how you will distinguish a refill response from an intake response, and a
   refill order from the first fill, **in your own records**, since the API will not distinguish
   them for you

## Related

> [card] [Appointments and scheduling](https://openloop.mintlify.site/cookbook/appointments-and-scheduling.md)
>
> The stage before this one: offer availability and book visits

> [card] [Upsell and cross-sell](https://openloop.mintlify.site/cookbook/upsell-and-cross-sell.md)
>
> The next stage: subscriptions, retention, and the commercial side of a refill

> [card] [Cancel, pause and refund](https://openloop.mintlify.site/cookbook/cancel-pause-refund.md)
>
> When this stage goes wrong: the patient wants to stop, pause, or have their money back

> [card] [Integration flow](https://openloop.mintlify.site/cookbook/integration-flow.md)
>
> The intake mechanics a refill submission reuses, including both silent failures

> [card] [Order status and tracking](https://openloop.mintlify.site/cookbook/order-status-and-tracking.md)
>
> How order state reaches you once a refill is approved

> [card] [Prescription events](https://openloop.mintlify.site/cookbook/prescription-events.md)
>
> The four webhook events and every attribute they carry


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