Skip to main content
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: 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.
Locked by check customer-name-required.
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.
Locked by check prices-carry-a-provider-id.

What comes back

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

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.

Gotchas

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

Integration flow

The leg before this one: patient, intake, and the encounter the platform creates

Order status and tracking

The leg after: order status and tracking, delivered as prescription webhook events

Prescription events

Every event and attribute: the four lifecycle verbs, data.status and the timestamps

Payment failure

When this stage goes wrong: an abandoned session, a declined card, a declined proration, a declined off-session charge (a 400)