Product upgrades
The upgrade flow changes an existing eligible Stripe subscription. It is separate from creating a new Checkout Session, assigning a manual grant or changing the default product.
Select a subscription and destination
const active = await client.products.listActive({ limit: 20 })
const source = active.data[0]
if (!source) throw new Error('No active subscription to upgrade')
const options = await client.products.listUpgradeOptions({
sourceProductId: source.product.id,
limit: 20
})Let the customer select the intended source and destination in your UI; choosing data[0] above only shows the response shape. Both list methods return data and hasMore. For another page, pass the last returned product ID as startingAfter, keeping the same source product when listing upgrade options.
Only active, owned Stripe subscriptions with a single fixed recurring item participate. The source must have an eligible paid access invoice and no cancellation, pause or schedule, and use automatic collection. Manual and default grants do not become paid upgrade sources.
The destination must be an available mapped product with an active, licensed, per-unit recurring Stripe price in the same currency. Products already active or reserved for another change are excluded. A hidden option is not necessarily a frontend filtering bug; recheck current subscription and product configuration.
Preview, then confirm
const change = {
sourceProductId: selectedSourceProductId,
targetProductId: selectedTargetProductId
}
const preview = await client.products.previewUpgrade(change)
// Render preview.currency, preview.amountDue and preview.lines for consent.
const result = await client.products.confirmUpgrade(change)Preview calculates Stripe’s invoice without applying the change or collecting payment. Confirmation uses current pricing; a preview is not a locked quote. Amounts use the API’s currency amount units, not a universally fixed number of decimal places. Format using the returned currency rather than always dividing by 100.
Handle the result
| Status | Next step |
|---|---|
pending_payment | Persist upgradeId, then send the customer to paymentUrl. |
processing | Keep the change pending and recheck with processUpgrade. |
completed | Reload product and usage state; paid access is activated. |
const updated = await client.products.processUpgrade({
upgradeId: savedUpgradeId
})Store upgradeId before redirecting. Repeating processing for a completed upgrade preserves the existing usage state rather than granting a fresh unused allowance each time. Do not create another subscription to recover an in-progress upgrade.
Recover from changed eligibility
Reload active subscriptions and options if the source, price or destination changed between listing and confirmation. Resolve a cancellation, pause, schedule, unpaid access invoice or conflicting pending change before trying again. Do not silently fall back to a different source subscription: that changes what the customer consented to modify.
Webhook reconciliation can complete after a provider response. Inspect webhook processing and the customer’s history when payment was accepted but access is still pending.