Switch Plan on an Open Checkout

Use this flow when the customer picks a different plan on your page while the checkout is already mounted — for example, switching from a monthly to a yearly plan on a paywall. The checkout reads the session — amount, plan, and available payment methods — once, when it mounts. Updating the session on your server doesn’t change a checkout that is already on screen, and checkout.update() can’t change it either: it updates only display settings such as locale and theme. To show the new price, update the session and then remount the checkout.

If you skip the remount, the checkout keeps showing the previous price. Apple Pay and Google Pay open their payment sheets with that previous amount, so the customer may approve a price that differs from the updated session.

Steps

Pause payments. Call checkout.setPaymentsEnabled(false) so the customer can’t start a payment while the session is changing.
Update the session on your server. Call PATCH /client-session/{id} with the new plan. The session ID stays the same.
Remount the checkout. Call await checkout.unmount(), then mount() again with the same clientToken. The checkout loads the updated session and shows the new price.

Remounting clears the form, so anything the customer has typed — such as card details — is lost.

Update the Session

Send only the objects you want to change. Each top-level object you send — plan, customer, subscription, payment, options — replaces that object in the session as a whole. Objects you don’t send stay as they are.

cURL

curl -X PATCH https://api.paynext.com/client-session/cs_d3b07384-d9a5-4d16-a5b1-3fa3d9b0b123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 2.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": { "id": "plan_8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e" }
  }'

The response is the updated session, in the same format as the create response.

Because plan is replaced as a whole, a custom plan.price you set earlier is dropped unless you send it again. A custom price is supported for one-off plans only.

Remount the Checkout

Call your server endpoint from the client, then remount with the same token:

import { PayNextCheckout, type PayNextConfig } from '@paynext/sdk'

const config: PayNextConfig = {
  clientToken: 'cs_d3b07384-d9a5-4d16-a5b1-3fa3d9b0b123',
  environment: 'sandbox',
  // ... other checkout config options
}

let checkout = new PayNextCheckout()
await checkout.mount('paynext-checkout', config)

async function switchPlan(planId: string) {
  // 1. Block payments while the session changes.
  checkout.setPaymentsEnabled(false)

  try {
    // 2. Your server calls PATCH /client-session/{id} with the new plan.
    const response = await fetch('/api/switch-plan', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ sessionId: config.clientToken, planId }),
    })
    if (!response.ok) throw new Error('Failed to update the session')
  } catch (error) {
    // The session is unchanged — re-enable payments on the current plan.
    checkout.setPaymentsEnabled(true)
    throw error
  }

  // 3. Remount so the checkout reads the updated session.
  await checkout.unmount()
  checkout = new PayNextCheckout()
  await checkout.mount('paynext-checkout', config)
}

The remount takes paymentsEnabled from config, so payments work again after it — unless your config sets paymentsEnabled: false to gate them behind your own UI.

Instead of updating the session, you can also create a new session for the new plan and mount the checkout with its ID. Updating keeps the same session ID, so you don’t need to replace the token you stored.

Update Configuration at Runtime — what checkout.update() can change without a remount
Handle Expired Sessions — create a new session when the current one expires

Getting Started

Use Cases

Customization

Constants

Steps

Update the Session

Remount the Checkout

​Steps

​Update the Session

​Remount the Checkout

​Related

Steps

Update the Session

Remount the Checkout

Related