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

# Upsell and cross-sell

> Cross-sell at checkout, upgrade a subscription with PUT /v0.1/subscriptions, and retain with pauses, billing portals and coupons.

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.

> [!TIP]
>
> 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.

```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",
    "customer_data": { "email": "jordan.avery@example.com", "name": "Jordan Avery" },
    "items": [
      { "provider_price_id": "price_...primary", "quantity": 1 },
      { "provider_price_id": "price_...addon",   "quantity": 1 }
    ],
    "provider_promotion_code_ids": ["promo_..."]
  }'
```

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

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

> [!TIP]
>
> 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.

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

```json Response theme={null}
{ "data": { "subscriptions": [ { "provider_subscription_id": "sub_...", "status": "active",
                                 "items": [ { "provider_item_id": "si_...",
                                              "provider_price_id": "price_..." } ] } ] },
  "request_id": "..." }
```

```json 400 — email omitted theme={null}
{ "error": { "message": "email is required in query params", "error_code": "VALIDATION_ERROR" },
  "request_id": "..." }
```

```json 404 — no customer with that email theme={null}
{ "error": { "message": "Customer not found", "error_code": "NOT_FOUND" },
  "request_id": "..." }
```

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

> [!TIP]
>
> 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.

```bash curl theme={null}
curl "https://api-staging.openloophealth.com/v0.1/billing-portals" \
  -H "authorization: Bearer $TOKEN"
```

```json Response theme={null}
{ "data": { "configurations": [ { "provider_billing_portal_id": "bpc_...", "name": "Default" } ] },
  "request_id": "..." }
```

Note the envelope: this one answers under `data.configurations`, not `items` — a third shape
alongside the `items` and `data` envelopes *Getting started* describes.

> [!TIP]
>
> 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](https://openloop.mintlify.site/cookbook/payment-failure.md#recipe-a-prorated-upgrade-was-declined)
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.

> [!TIP]
>
> 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

| Field | Meaning | You key on it for |
| - | - | - |
| `data.subscriptions[]` | The subscriptions behind one billing email | Finding the subscription to upgrade — keyed by email, never by patient id |
| `provider_subscription_id` | The payment provider's subscription id | Every subsequent read, change, pause, invoice list and cancel |
| `provider_item_id` | The id of one line on the subscription | Changing an existing line — sending a price alone **adds** a line instead |
| `status` | `active`, `past_due`, … | Detecting a declined proration after a plan change |
| `data.configurations[]` | Billing-portal configurations, each with a `provider_billing_portal_id` | Opening a portal session |
| `data.coupons[]` / `data.promotion_codes[]` | The discount catalogue, under `data` rather than `items` | Attaching `provider_coupon_ids` / `provider_promotion_code_ids` at session level |
| `request_id` | Present on every response, success or failure | Support, when a discount or upgrade misbehaves |

## Gotchas

> [!NOTE]
>
> 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.

> [!NOTE]
>
> 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.

> [!NOTE]
>
> 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.

> [!NOTE]
>
> **`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

> [card] [Refills](https://openloop.mintlify.site/cookbook/refills.md)
>
> The stage before this one: a refill renews through the subscription

> [card] [Payments and checkout](https://openloop.mintlify.site/cookbook/payments-and-checkout.md)
>
> The checkout rules every pattern here depends on

> [card] [Payment failure](https://openloop.mintlify.site/cookbook/payment-failure.md)
>
> When a card or a prorated upgrade is declined: what to read, and what to tell the patient

> [card] [Cancel, pause and refund](https://openloop.mintlify.site/cookbook/cancel-pause-refund.md)
>
> When retention fails: cancel now or at period end, pause for N cycles, refund an invoice


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