What you’ll do
1
Tell 'never paid' from 'paid and stuck'
No subscription or paid invoice on the billing email means no payment. The clinician’s charting
note still creates the order (
prescription.created), but whether it was paid for is not on the
prescription events — payment state lives on the billing events (invoice.paid,
subscription.*) and the billing reads below.2
Read the subscription, not the update response
PUT /v0.1/subscriptions/{provider_subscription_id} returns the subscription, never the
payment result.3
Find the unpaid invoice
GET /v0.1/subscriptions/{provider_subscription_id}/invoices?status=open is the open charge —
and a 404, not an empty list, if the id is wrong.4
Tell the patient what actually happened
Two of the four look identical from your side; one means the plan already changed, and the off-session
400 means nothing was created.The four failures, and what each leaves behind
The first two are indistinguishable from your side, and they need the same action. The third is the
one that catches integrators out: the
PUT succeeded, so nothing in your code raised an error.
Recipe · Confirm that nothing was paid
Read the billing side by the email you passed incustomer_data on the session — both reads
require email, and omitting it returns 400 with email is required in query params, not an
unfiltered list.
400 without email is observed on staging by
check unknown-billing-email-is-404. The response shape for a billing customer that exists but
never paid is not exercised here.)
On the prescription side, no prescription event follows an abandoned session: the events
describe an order, and an unpaid session never creates one (by arrangement — the events cannot be
exercised by the conformance runner, so this is prose, not a check).
There is no order read on the partner surface — see API status. If a patient insists they paid
and the billing reads show nothing, escalate with the request_id from your checkout-session
response rather than writing a record to compensate.
What a declined card leaves behind
The decline happens on the payment provider’s hosted page, and the patient retries there. Two consequences for your integration:- You will not see the decline. The published reference documents only a
POSTon/v0.1/checkouts/sessions— there is nothing to read a session back with (see Payments and checkout) — and the prescription webhook events (by arrangement) describe orders, which a declined card never creates (see Prescription events). No new subscription or paid invoice on the billing reads is the only signal you have. - Do not re-send an old checkout URL. Treat the hosted
urlas short-lived and single-use: with nothing to read a session back with, you cannot ask whether it is still valid. If the patient returns later, create a new session and redirect them to the fresh URL.
Recipe · A prorated upgrade was declined
PUT /v0.1/subscriptions/{provider_subscription_id} returns the subscription, not the payment
result. When the prorated invoice is declined, the call still succeeds, the item change stays
applied, and the subscription moves to past_due — so the patient is on the new plan with an
unpaid charge behind it.
The update also validates the body before it looks the subscription up, which is worth knowing when
you are reading a failure after the fact:
Validation runs first, so a
400 tells you nothing about whether the subscription exists — fix the
body, then read the 404 as the answer about the id.
Locked by check
update-needs-a-field-and-a-real-subscription.Reading that subscription’s invoices
The invoice read is the one you will reach for during a live billing incident, so know its three shapes before you wire it into a runbook:
The last two rows were observed on staging on 2026-09-11 and are locked by the check below. The
first is the published reference’s shape: verifying it needs a subscription with a real charge
behind it, which these checks deliberately do not create. What the check does confirm live is that
open and paid are the only values the filter accepts.
That 404 has two consequences. It is not an empty collection: on a wrong id there is no
items array to iterate, so code that assumes one will throw rather than report “nothing unpaid”.
And its message is not the Subscription not found that
GET /v0.1/subscriptions/{provider_subscription_id} returns for that same id — it is the payment
provider’s own words, wrapped and passed through. An error handler that string-matches
Subscription not found will miss this route entirely. Key on the status and on
error.error_code (NOT_FOUND), never on the message text.
Locked by check
subscription-invoices-validates-status-then-404s.Which read answers which question
The
404 matters when you are triaging: on these billing lookups it means no billing customer
carries that email — most often a patient who never reached checkout, or an address that differs
from the one they paid with. It is not evidence that their invoices are missing. Subscription
lookup is keyed by billing email rather than by patient id, so carry that email on your patient
record — see Upsell and cross-sell.
Locked by check
unknown-billing-email-is-404.The prescription side carries no payment state
Payment state is not on the prescription webhook events. The four deliverable prescription events —prescription.created, prescription.ordered, prescription.shipped and
prescription.cancelled — describe only the order’s fulfilment lifecycle (data.status and
data.timestamps.*); none of them tells you whether the order was paid for. See Prescription
events.
The payment signal lives on the billing events instead: invoice.paid says an invoice settled,
and subscription.created / subscription.updated — with data.status past_due or unpaid —
say a subscription’s charge did not. All three are com.openloop.payments events; see Events. The
same state is readable synchronously via the billing reads above (GET /v0.1/subscriptions,
GET /v0.1/invoices).
To join a prescription event to its billing state, correlate on the patient. data.emr_patient_id,
when the event carries it, is your /v0.1 patient id, so start from the patient you already hold.
Without it the event has only data.patient_ref, an opaque reference — not guaranteed to be the
/v0.1 patient id, and not the billing email — so the mapping to the billing reads follows the
correlation you agree at registration.
What comes back
What to tell the patient
Four failures, four messages. Keep them to the fact and the action:- Never finished checkout — “We never received a payment, so nothing has been ordered. Here is a fresh checkout link.” Send a new session; the old link is not worth re-sending.
- Card declined at checkout — the same message. From your side the two are identical, so do not tell them their card was declined when you cannot see that it was.
- Upgrade declined — “Your plan has changed, and the balance for it has not been paid yet.” The change is live, so do not tell them the upgrade failed. Point them at a billing portal to update the card (see Upsell and cross-sell), and quote the new recurring price rather than an exact prorated amount — previews cannot price a plan change, which Upsell and cross-sell holds to its own check.
- Off-session charge declined (
400) — “Your card was declined, so nothing has been set up yet; please try another card.” Nothing was created on our side, so there is nothing to undo: collect a new card and mint a newIdempotency-Keyfor the retry — see Retries and idempotency.
Gotchas
The subscription alone cannot tell you a change is awaiting payment. The published subscription
object has no pending-update field — that is the reference’s shape, not something this cookbook
measured — so
status plus the open invoice is the only way to see an unpaid change. Read both.Statuses and error messages on this page — including the
400 and 404 rows of the invoice-read
table above — were observed against staging on 2026-09-11 by the checks named above. The past_due
and quantity behaviours were observed against a live subscription on 2026-09-08/10 and are not
re-run by these checks, which would have to put a real charge through a real card to reproduce
them.Related
Payments and checkout
The happy path this interrupts: create the session, and let payment create the order
Upsell and cross-sell
The plan change whose proration can decline, and the portal that fixes the card
Prescription events
The signed prescription webhooks — order lifecycle only; payment state is on the billing events

