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’scurrent_price_idpoints at.provider_price_id— the payment provider’s identifier, e.g.price_1AbC…. This is the onecheckouts/sessionsrequires.
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 theinvoice.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:
- The hosted checkout return. The patient lands back on your
success_urlwhen 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. - 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=paidlists what was charged (published;statusdefaults toopen, so passpaidexplicitly). Both are keyed by the billing email, not the patient id, and an email no billing customer has answers404(Customer not found), not an empty list — see Payment failure. - 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— carryingdata.statusand thedata.timestamps.*for each stage. They carry no payment state, and they identify the patient bydata.emr_patient_id, your/v0.1patient id, whenever the id is known. Without it onlydata.patient_refis left, an opaque reference that is not guaranteed to be the/v0.1patient 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 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.Related
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 timestampsPayment failure
When this stage goes wrong: an abandoned session, a declined card, a declined proration, a declined off-session charge (a
400)
