Skip to main content
Something did not get paid. By the end of this page you will know which of the four payment failures you are looking at, the one read that tells you, and what to say to the patient — instead of inferring it from a record that never appeared.

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 in customer_data on the session — both reads require email, and omitting it returns 400 with email is required in query params, not an unfiltered list.
No new subscription and no paid invoice for the email the patient checked out with is the answer: no payment was taken, so no order exists to be stuck. There is nothing to reconcile and nothing to cancel. (Published reference for both reads; the 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 POST on /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 url as 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.
After every plan change, read both of these before you tell the patient anything:

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 new Idempotency-Key for the retry — see Retries and idempotency.

Gotchas

A declined proration leaves the change applied. The patient has the new plan and an unpaid invoice, and your PUT returned 200. Do not re-send the update to “retry” the payment: the change already happened, and a repeated update can add a second line rather than replacing the first — see Retries and idempotency. Fix the payment, not the subscription.
quantity resets to 1 on a price change. Observed against a live subscription on staging, 2026-09-08/10: change an item’s price without sending quantity and the item comes back at 1. Send quantity explicitly on every item you change, and read it back from the response.
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.

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