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 ofitems, so a session can carry the primary treatment
plus add-ons in one payment.
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.
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.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.
data.configurations, not items — a third shape
alongside the items and data envelopes Getting started describes.
Locked by check
billing-portals-listable.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}—statusGET /v0.1/subscriptions/{provider_subscription_id}/invoices?status=open— any unpaid invoice the change left behind
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
GET /v0.1/products?active=true— is the upsell product in the catalogue at all?GET /v0.1/products/{product_id}/prices— does it have aprovider_price_id?GET /v0.1/couponsandGET /v0.1/promotion-codes— do the discounts you plan to offer exist?
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.Related
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

