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

# Payments and checkout

> Create a checkout session with provider_price_id, match type to the price interval, and understand what payment does and does not trigger on the platform side.

By the end of this page you will be able to take payment for a treatment, and you will know what
happens on our side afterwards — and why paying is not, by itself, what creates the order.

## What you'll do

**1. Find a sellable price**

`GET /v0.1/products?active=true`, then `GET /v0.1/products/{product_id}/prices` for its
`provider_price_id`.

**2. Create the session**

`POST /v0.1/checkouts/sessions` with `type` matching the price's `billing_interval`.

**3. Redirect the patient**

Send them to the hosted URL, and keep the session id — there is no route to read one back.

**4. Confirm what payment created**

The billing side is a read — `GET /v0.1/subscriptions?email=` and the invoices — or the billing
webhook events (`invoice.paid`, `subscription.*`). Payment state is not carried on prescription
events.

## Use the platform's payment endpoints, not the provider directly

Route checkout through `/v0.1/checkouts/sessions`. Integrating directly with the payment provider
forecloses upsell and downstream commerce logic, is expensive to unwind after launch, and detaches
the payment from the clinical record — which is what keeps orders joined to intakes.

## Recipe 3.1 · Create a checkout session

`POST /v0.1/checkouts/sessions` — the schema marks only `type` as required, but three more are
required in practice and each produces its own `400`:

| Field | Notes |
| - | - |
| `type` | **Must match the price you are selling.** `subscription` for a recurring price, `payment` for a one-time price. Mismatching returns `400`: *"You specified `payment` mode but passed a recurring price."* Check `billing_interval` on the price first |
| `ui_mode` | e.g. `hosted` |
| `success_url`, `cancel_url` | Your return destinations |
| `customer_data.email` **and** `customer_data.name` | **Both** required unless you pass `provider_customer_id`. Email alone returns `customer_data.name is required when provider_customer_id is not provided` |
| `items[].provider_price_id` | **Not `price_id`.** Using `price_id` returns `each item requires provider_price_id` |
| `items[].quantity` | |

Optional: `currency`, `provider_coupon_ids`, `provider_promotion_code_ids`, `return_url`,
`metadata`. A successful call returns the session id, a provider customer id, and a hosted
checkout URL.

```bash curl theme={null}
curl -X POST https://api-staging.openloophealth.com/v0.1/checkouts/sessions \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "type": "subscription",
    "ui_mode": "hosted",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "currency": "usd",
    "customer_data": { "email": "jordan.avery@example.com", "name": "Jordan Avery" },
    "items": [ { "provider_price_id": "<from the product's prices>", "quantity": 1 } ]
  }'
```

```json Response theme={null}
{ "data": { "provider_checkout_session_id": "...", "url": "https://..." }, "request_id": "..." }
```

> [!TIP]
>
> Locked by check `customer-name-required`.

> [!TIP]
>
> Locked by check `provider-price-id-not-price-id`.

## Recipe 3.2 · Read the price ids off a product

Every price record carries **two** ids, and they are not interchangeable:

* **`id`** — the platform's own identifier. This is what a product's `current_price_id` points at.
* **`provider_price_id`** — the payment provider's identifier, e.g. `price_1AbC…`. **This is the
  one `checkouts/sessions` requires.**

The lookup is: `GET /v0.1/products` → choose a product → `GET /v0.1/products/{product_id}/prices`
→ read `provider_price_id`. Passing `current_price_id` into a checkout session will fail.

```bash theme={null}
GET /v0.1/products?active=true            # prefer active products
GET /v0.1/products/{product_id}/prices    # provider_price_id and billing_interval
```

> [!TIP]
>
> Locked by check `prices-carry-a-provider-id`.

## What comes back

| Field | Meaning | You key on it for |
| - | - | - |
| `data.provider_checkout_session_id` | The payment provider's session id | Your own record of the attempt — there is no route to read the session back |
| `data.url` | The hosted checkout URL | Redirecting the patient |
| `request_id` | Present on every response | Support, when a session fails |

The confirmation that a payment landed is the billing read keyed by the email you put in
`customer_data`, not a payment-provider dashboard and not the return to `success_url` — see *What
happens after payment* below.

## Checking your environment

| Check | Expected | If it fails |
| - | - | - |
| `GET /v0.1/configs` | `200` with `payment_provider`, `status: ACTIVE`, and a non-empty `provider_account_id` and `publishable_key` | Your payment configuration is missing. Nothing downstream will work |
| `GET /v0.1/payment-methods` | `200` | A `403` naming `payment_method_configurations_read` is a payment-provider configuration gap on the OpenLoop side. It does *not* block checkout. Report it with the `request_id`, then carry on |
| A checkout session with an `ACTIVE` product's `provider_price_id` | `200` with a checkout URL | `No such price` means a stale catalogue entry — see the warning below |

## What happens after payment

**Payment does not create the order; the clinician's charting note does.** You do not call an
order endpoint — there is none on the partner surface, read or write.

The sequence on the platform side: the patient pays (which, for a recurring price, creates the
subscription — confirmed by the `invoice.paid` / `subscription.*` billing events or the billing
reads); a clinician reviews the intake and charts a prescription, which creates the order
(`prescription.created`); the order then goes to the pharmacy (`prescription.ordered`) and ships
(`prescription.shipped`). Payment state is **not** carried on the prescription events — track it from
the billing events or the subscription / invoice reads. You learn about each prescription step from
its events, not from a read.

So your side of it has three parts:

1. **The hosted checkout return.** The patient lands back on your `success_url` when they finish
   the hosted page (published). Treat it as "the patient left the page", not as proof of payment:
   it is a browser redirect, and anyone can load that URL.
2. **The billing reads, for the payment itself.** For a recurring price,
   `GET /v0.1/subscriptions?email=<the customer_data email>` returns the subscription once payment
   has created it; for either kind, `GET /v0.1/invoices?email=<the customer_data email>&status=paid`
   lists what was charged (published; `status` defaults to `open`, so pass `paid` explicitly). Both
   are keyed by the billing email, not the patient id, and an email no billing customer has
   answers `404` (`Customer not found`), not an empty list — see *Payment failure*.
3. **The prescription events, for the order.** If you have arranged webhook delivery with your
   implementation contact, the order arrives as the signed prescription events —
   `prescription.created`, `prescription.ordered`, `prescription.shipped`, `prescription.cancelled` —
   carrying `data.status` and the `data.timestamps.*` for each stage. They carry no payment state, and
   they identify the patient by `data.emr_patient_id`, your `/v0.1` patient id, whenever the id is
   known. Without it only `data.patient_ref` is left, an opaque reference that is not guaranteed to be
   the `/v0.1` patient id and is not the billing email; how that correlates to your patients is agreed
   when the endpoint is registered. See *Prescription events* and *Order status and tracking*.

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

curl "https://api-staging.openloophealth.com/v0.1/invoices?email=jordan.avery@example.com&status=paid" \
  -H "authorization: Bearer $TOKEN"
```

## Gotchas

> [!NOTE]
>
> Checkout works end to end — a hosted session returns a live session id and checkout URL. The
> failure most integrators hit is a **stale price id**, described below, not a broken endpoint.

> [!WARNING]
>
> **There is no route to read a session back.** The reference documents only
> `POST /v0.1/checkouts/sessions`; a `GET` on a session id returns a `403` about the `Authorization`
> header, which is what an unmapped method looks like. Keep the session id and URL from the create
> response.

> [!WARNING]
>
> **Prefer `ACTIVE` products, and expect archived ones to fail.** Some tenants carry `ARCHIVED`
> products whose `provider_price_id` values belong to a **previous payment account**. Using one
> returns:
>
> ```
> Failed to create Stripe checkout session: No such price: 'price_1U8KY4...'
> ```
>
> That error means the platform accepted your request and the provider rejected the price — the id
> is real, it just lives on a different account. It is **not** a sign that checkout is unavailable.
> Filter with `GET /v0.1/products?active=true` and, if a price fails this way, ask your OLH implementation contact whether that product's catalogue entry is stale rather than debugging your
> own code.

> [!NOTE]
>
> **There is no post-payment update for you to send.** The published reference documents no order
> route at all — no read, and no `PATCH`, `PUT` or `POST` — so the platform reconciles the order
> itself and your side of the flow is the billing read plus the events you receive. If you believe
> an order needs correcting, escalate it with the checkout `request_id` and, if you have one, the
> order's `data.resource_id` and the envelope `id` from the latest prescription event, rather than
> looking for a write.

> [!NOTE]
>
> **Use a checkout session to take a payment; use `/v0.1/intents/setups` to store a payment method
> without charging for it.** Both are published: `POST /v0.1/checkouts/sessions` returns a hosted URL
> the patient pays on, while `POST /v0.1/intents/setups` (read back with
> `GET /v0.1/intents/setups/{provider_setup_intent_id}`) exists for saving a method for later. This
> cookbook has exercised the checkout session end to end and **has not** exercised the setup-intent
> path, so confirm the capture behaviour with your OLH implementation contact before you build a flow
> that depends on it.

> [!NOTE]
>
> **You do not have to create the billing customer first.** Passing `customer_data` with `email` and
> `name` on the session is enough — the create response carries a provider customer id back. Use
> `POST /v0.1/billing-customers` (which requires `email`) only when you need the customer to exist
> before there is a session to attach it to; otherwise let the session create it and store the id it
> returns.

## Related

> [card] [Integration flow](https://openloop.mintlify.site/cookbook/integration-flow.md)
>
> The leg before this one: patient, intake, and the encounter the platform creates

> [card] [Order status and tracking](https://openloop.mintlify.site/cookbook/order-status-and-tracking.md)
>
> The leg after: order status and tracking, delivered as prescription webhook events

> [card] [Prescription events](https://openloop.mintlify.site/cookbook/prescription-events.md)
>
> Every event and attribute: the four lifecycle verbs, `data.status` and the timestamps

> [card] [Payment failure](https://openloop.mintlify.site/cookbook/payment-failure.md)
>
> When this stage goes wrong: an abandoned session, a declined card, a declined proration, a declined off-session charge (a `400`)


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