Skip to main content
Change a customer’s subscription to a different plan. Choose whether to charge immediately (with proration) or wait until the next billing date.

​
Choose Your Approach

I want to…ApproachPayment
Charge now and reset billing cycleImmediate PaymentCharged immediately
Change plan, charge laterSchedule ChangeNext billing date

​
Change With Immediate Payment

Charge the customer now for the new plan. Use when upgrades should take effect immediately.
1

Create a client session

Include the customer, subscription, and new plan:
cURL
curl -X POST https://api.paynext.com/client-session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 1.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "id": "cus_11dfa45f-23b1-40f4-9e9b-c9d485915528" },
    "plan": { "id": "plan_8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e" },
    "subscription": {
      "id": "sub_11dfa45f-23b1-40f4-9e9b-c9d485915528",
      "proration_billing_mode": "prorated_immediately"
    },
    "options": { "payment_methods_mode": "saved_or_new" }
  }'
2

Mount the SDK

Display checkout with the customer’s saved payment method:
const checkout = new PayNextCheckout()

checkout.mount('checkout-container', {
  clientToken: session.id,
  environment: 'sandbox',
  onCheckoutComplete: (result) => {
    // Subscription updated, billing cycle reset
    console.log('Plan changed:', result.payment_id)
  },
  onCheckoutFail: (error) => {
    // Customer can retry with different card
    // Subscription stays on old plan until payment succeeds
  }
})
Outcomes:
  • Success: Plan updates immediately, billing cycle resets to today
  • Failure: Subscription stays on old plan; customer can retry with a different card

​
Schedule Plan Change

Change the plan without charging now. The new price applies at the next billing date.
cURL
curl -X PATCH https://api.paynext.com/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 1.0.0" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": { "id": "plan_8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e" },
    "subscription": { "id": "sub_887934f2-de1a-4b28-a288-ba8f70c71bd3" }
  }'
The plan changes immediately in the system. The next charge (on the existing billing date) uses the new plan’s price.

​
Silent Plan Change (No UI)

To change plans without showing checkout, use the API-only approach. This charges the customer’s saved payment method directly.
Background charges have no card update UI. If payment fails, you must notify the customer separately.