Skip to main content
By the end of this page you will know the three ways to sell more to an existing patient, and which of them exist today.

What you’ll do

1

Add the upsell to the catalogue

An upsell is a product: it needs its own product, price and provider_price_id.
2

Cross-sell at checkout

One session carries several items, with discounts attached at session level.
3

Upgrade an existing subscriber

Find the subscription by email, then PUT the change.
4

Retain rather than cancel

Pause, open a billing portal, or run a retention session.

There is no upsell endpoint

Nothing in the partner surface is named “upsell”. It is composed from products, prices, coupons, promotion codes, checkout sessions and subscriptions. That is why routing checkout through /v0.1/checkouts/sessions rather than integrating the payment provider directly matters — going direct forecloses every pattern below. An upsell is modelled as a product. Give it its own product and price, and it flows through the same catalogue, checkout and order path as a primary treatment.
Locked by check upsell-is-a-product.

Recipe 7.1 · Cross-sell at checkout

A checkout session takes an array of items, so a session can carry the primary treatment plus add-ons in one payment.
The type must match the prices in items — subscription for recurring, payment for one-time. Mixing them, or using payment with a recurring price, returns a 400 from the payment provider. Discounts attach to the session, not to an item: provider_coupon_ids and provider_promotion_code_ids are both session-level arrays. Read the available ones from GET /v0.1/coupons and GET /v0.1/promotion-codes (both 200), or create them with POST on the same paths. Remember both checkout rules from Payments and checkout: customer_data needs email and name, and items take provider_price_id — never the platform price id.
Locked by check discount-catalogue-readable.

Recipe 7.2 · Find the subscription you are about to upgrade

Subscription lookup is keyed by email, not by patient id — so carry the billing email alongside your patient record, or you cannot find the subscription you need to upgrade. email is required: without it the call is a 400 naming it.
An email with no billing customer behind it is a 404, not an empty list — observed against staging on 2026-09-11. Do not read that 404 as “this subscriber has no subscriptions”.
Locked by check subscription-lookup-is-by-email.
Once you hold the provider_subscription_id, the rest of the subscription surface is addressed by it: read with GET /v0.1/subscriptions/{provider_subscription_id}, change with PUT /v0.1/subscriptions/{provider_subscription_id}, list invoices with GET /v0.1/subscriptions/{provider_subscription_id}/invoices, and cancel with DELETE /v0.1/subscriptions/{provider_subscription_id}. Those four are read from the published reference on 2026-09-11 and are not exercised by this cookbook — a plan change or a cancel needs a paid subscription in your tenant. Cancel, pause and refund documents the cancel body and its rejections; Retries and idempotency documents why re-sending a PUT adds a second line item.

Recipe 7.3 · Open a billing portal instead of cancelling

GET /v0.1/billing-portals lists the portal configurations your tenant has. You need the provider_billing_portal_id off one of them before you can create a session against it.
Note the envelope: this one answers under data.configurations, not items — a third shape alongside the items and data envelopes Getting started describes.
Locked by check billing-portals-listable.
Three more retention levers are published and read from the reference on 2026-09-11, not exercised here, because each needs a live paid subscription: POST /v0.1/billing-portals/{provider_billing_portal_id}/sessions opens a portal session for the patient, POST /v0.1/billing-portals/retention-sessions is the platform’s purpose-built cancel-deflection surface, and POST/DELETE on /v0.1/subscriptions/{provider_subscription_id}/pauses pause and resume. Cancel, pause and refund documents the pause body and what a pause does and does not change. If you build your own save flow instead of using a retention session, the offers you make will not be visible to the platform.

Recipe 7.4 · Read back what a plan change actually did

PUT /v0.1/subscriptions/{provider_subscription_id} returns the subscription, not the payment result, so read the state back after every plan change:
  • GET /v0.1/subscriptions/{provider_subscription_id} — status
  • GET /v0.1/subscriptions/{provider_subscription_id}/invoices?status=open — any unpaid invoice the change left behind
If the prorated invoice was declined, the change is still applied and the subscription moves to past_due. Payment failure owns that path — the order the two reads must be made in, what a 404 Subscription not found means there, and what to tell the patient. POST /v0.1/invoices/previews cannot show the price of a plan change. Its request schema in the API reference has exactly two properties — provider_subscription_id (required) and discounts — so there is no way to describe a changed item; the endpoint previews the subscription’s next invoice as it stands. Quote the new recurring price and tell the patient the prorated charge follows; do not promise an exact amount from a preview.
Locked by check previews-cannot-price-a-plan-change.

What to check first in your tenant

  1. GET /v0.1/products?active=true — is the upsell product in the catalogue at all?
  2. GET /v0.1/products/{product_id}/prices — does it have a provider_price_id?
  3. GET /v0.1/coupons and GET /v0.1/promotion-codes — do the discounts you plan to offer exist?
An upsell that is not in the catalogue cannot be sold, and a catalogue entry whose price sits on a retired payment account fails at checkout with No such price — see Payments and checkout.

What comes back

Gotchas

Every response shape on this page is observed against staging on 2026-09-11 except where the text says a route is read from the published reference and not exercised here. Those are the plan change, the cancel, the pauses and the portal and retention sessions: each needs a live paid subscription in your tenant, which this cookbook does not create.
This page describes today’s mechanism, composed from the commerce endpoints above. If OpenLoop ships a dedicated upsell feature, prefer that once it is available.
The check previews-cannot-price-a-plan-change locks the requirement: a body without provider_subscription_id is rejected with 400. That the request takes only those two properties is the published request schema, not something this cookbook measured.
entitlements is undocumented. Products carry an entitlements field and the reference declares it as an empty schema, so its shape is unspecified. It appears to be how bundled add-ons are expressed. Inspect a real product rather than assuming a shape, and do not build logic on it until it is documented.

Refills

The stage before this one: a refill renews through the subscription

Payments and checkout

The checkout rules every pattern here depends on

Payment failure

When a card or a prorated upgrade is declined: what to read, and what to tell the patient

Cancel, pause and refund

When retention fails: cancel now or at period end, pause for N cycles, refund an invoice