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, onPOST /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.
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.
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 aprescription.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)
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_idis your/v0.1patient id, theidthatGET /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, nevernull.data.patient_refis an opaque reference, not guaranteed to be the/v0.1patient id, and the event carries no email or phone. If your patients exist only throughPOST /v0.1/patients, how an event withoutemr_patient_idis correlated to them is agreed with your implementation contact when the endpoint is registered.data.prescribed_product.codeis a product code, not a/v0.1product id.- Nothing on the event points back at your submission. It carries no
encounter_idand no questionnaire response id. To tell the refill order from the first fill, comparedata.timestamps.created_atwith 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.createdfor a newresource_id; there is no fill-number or refill flag in the contract, so distinguish it in your own records (see below).
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 onGET /v0.1/subscriptions/{provider_subscription_id}/invoices, which is how you reconcile a refill
shipment against what the patient was charged.
Gotchas
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
- You have the refill questionnaire id for each program, in your own configuration
- 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 nodata.emr_patient_id - 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
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

