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

# Payment failure

> Abandoned checkout, declined card, declined prorated upgrade, or a declined off-session charge (a 400): what to read, and what to tell the patient.

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

| What happened | What exists afterwards | The read that shows it |
| - | - | - |
| The patient never finished the hosted checkout | The patient record and the billing customer the session created — no order, no subscription, no paid invoice | `GET /v0.1/subscriptions?email=<billing_email>` and `GET /v0.1/invoices?email=<billing_email>&status=paid` show nothing new; no prescription event follows |
| Their card was declined on the hosted checkout page | The same: the provider keeps them on its own page to retry | The same read |
| A prorated upgrade was declined after the plan change | The plan change **is applied**, the subscription is `past_due`, and the proration invoice is open | `GET /v0.1/subscriptions/{provider_subscription_id}` and its `invoices?status=open` |
| An off-session charge on `POST /v0.1/subscriptions` was declined | Nothing: the call answers `400` with `error_code` `PROVIDER_ERROR`, and no subscription is created. The checks cannot decline a card, so this row is not staging-observed. On the on-session posture the decline surfaces in the browser after a `200` instead | The `400` itself; `GET /v0.1/subscriptions?email=<billing_email>` afterwards shows no new subscription |

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.

```bash curl theme={null}
curl "https://api-staging.openloophealth.com/v0.1/subscriptions?email=<billing_email>" \
  -H "authorization: Bearer $TOKEN"

curl "https://api-staging.openloophealth.com/v0.1/invoices?email=<billing_email>&status=paid" \
  -H "authorization: Bearer $TOKEN"
```

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:

| Request to `PUT /v0.1/subscriptions/{provider_subscription_id}` | Observed on staging, 2026-09-11 |
| - | - |
| `{}` | `400` — `At least one field must be provided for update` |
| `metadata: {}` and nothing else | `400` — the same message: an empty metadata object is not an update |
| `items: []` | `400` — `items must be a non-empty array` |
| A valid field, but an id no subscription has | `404` — `Subscription not found` |

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.

> [!TIP]
>
> 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:

```bash curl theme={null}
curl "https://api-staging.openloophealth.com/v0.1/subscriptions/<provider_subscription_id>" \
  -H "authorization: Bearer $TOKEN"

curl "https://api-staging.openloophealth.com/v0.1/subscriptions/<provider_subscription_id>/invoices?status=open" \
  -H "authorization: Bearer $TOKEN"
```

```json Response theme={null}
{ "data": { "subscription": { "provider_subscription_id": "...", "status": "past_due",
            "items": [ { "provider_item_id": "...", "quantity": 1, "price": { "provider_price_id": "..." } } ] } },
  "request_id": "..." }
```

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

| Request to `GET /v0.1/subscriptions/{provider_subscription_id}/invoices` | Result |
| - | - |
| `?status=open`, or no `status` at all | `200` with that subscription's open invoices; `open` is the default |
| `?status=` anything but `open` or `paid` | `400` — `Invalid status. Must be one of: open, paid`, returned **before** the subscription is looked up |
| A valid `status`, but an id no subscription has | `404` — `Failed to list stripe invoices by subscription id: No such subscription: '<id>'` |

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.

> [!TIP]
>
> Locked by check `subscription-invoices-validates-status-then-404s`.

## Which read answers which question

| Your question | The call | What you get |
| - | - | - |
| Did this patient pay at all? | `GET /v0.1/invoices?email=<billing_email>&status=paid`, and for a recurring price `GET /v0.1/subscriptions?email=<billing_email>` | No paid invoice and no subscription until a payment lands |
| Is the subscription healthy? | `GET /v0.1/subscriptions/{provider_subscription_id}` | `200`; `status` is `past_due` after a declined proration. An id no subscription has is `404` — `Subscription not found` |
| Which charge is unpaid? | `GET /v0.1/subscriptions/{provider_subscription_id}/invoices?status=open` | The open invoices for that subscription. `status` is `open` or `paid` only, and `open` is the default; an id no subscription has is `404` carrying the provider's message, **not** an empty list |
| What is unpaid for this billing email? | `GET /v0.1/invoices?email=<billing_email>&status=open` | `email` is required — without it, `400` with `email is required in query params`. An email no billing customer has is `404` with `Customer not found`, **not** an empty list |
| Which subscription belongs to this email? | `GET /v0.1/subscriptions?email=<billing_email>` | Same two shapes: `400` without `email`, `404` with `Customer not found` for an unknown one |

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

> [!TIP]
>
> 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

| Field | Meaning | You key on it for |
| - | - | - |
| `items` on `GET /v0.1/invoices?status=paid` | The billing email's paid invoices | "Did they pay?" |
| `invoice.paid` / `subscription.*` (billing events; see *Events*) | An order's payment state is on the billing events, not the prescription events | A payment problem on an order that exists |
| `data.subscription.status` | The provider's subscription status; `past_due` after a declined proration | Whether the last change was actually paid for |
| `data.subscription.items[].quantity` | Quantity per line, as it stands after your update | Catching the reset described below |
| `error.message` and `error.error_code` | `VALIDATION_ERROR` on a `400`, `NOT_FOUND` on a `404` | Telling a malformed request from a missing record |
| `request_id` | Present on every response, success or failure | The one value to log and to quote when you escalate |

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

> [!WARNING]
>
> **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.

> [!WARNING]
>
> **`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.

> [!NOTE]
>
> **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.

> [!NOTE]
>
> 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

> [card] [Payments and checkout](https://openloop.mintlify.site/cookbook/payments-and-checkout.md)
>
> The happy path this interrupts: create the session, and let payment create the order

> [card] [Upsell and cross-sell](https://openloop.mintlify.site/cookbook/upsell-and-cross-sell.md)
>
> The plan change whose proration can decline, and the portal that fixes the card

> [card] [Prescription events](https://openloop.mintlify.site/cookbook/prescription-events.md)
>
> The signed prescription webhooks — order lifecycle only; payment state is on the billing events


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