Skip to main content
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

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.
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.
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.
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). Both of intake’s silent failures apply here unchanged — see Gotchas.
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.
prescription.created (synthetic)
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.
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

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

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

Appointments and scheduling

The stage before this one: offer availability and book visits

Upsell and cross-sell

The next stage: subscriptions, retention, and the commercial side of a refill

Cancel, pause and refund

When this stage goes wrong: the patient wants to stop, pause, or have their money back

Integration flow

The intake mechanics a refill submission reuses, including both silent failures

Order status and tracking

How order state reaches you once a refill is approved

Prescription events

The four webhook events and every attribute they carry