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 the prorated difference nowImmediate PaymentCharged now
Change the plan now without chargingPatch with immediateNext billing date resets to today
Change the plan at the current billing datePatch with next_billing_dateExisting 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: 2.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
The prorated amount must reach the minimum charge amount of $0.50 (USD equivalent). If the calculation produces a smaller amount—common for downgrades or small upgrades—the client session returns a 400 error. Change the plan without a charge instead.

​
Change Without a Charge

When the prorated amount is below the minimum or you don’t want to charge now, change the plan with the subscription endpoint. Set change_mode to immediate to reset the billing cycle to today.
cURL
curl -X PATCH https://api.paynext.com/subscriptions \
  -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" },
    "subscription": {
      "id": "sub_887934f2-de1a-4b28-a288-ba8f70c71bd3",
      "change_mode": "immediate"
    }
  }'
The plan changes immediately. The next billing date resets to today plus the new plan’s period, and the next charge uses the new plan’s price.

​
Schedule Plan Change

Change the plan now and keep the existing billing date. Set change_mode to next_billing_date.
cURL
curl -X PATCH https://api.paynext.com/subscriptions \
  -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" },
    "subscription": {
      "id": "sub_887934f2-de1a-4b28-a288-ba8f70c71bd3",
      "change_mode": "next_billing_date"
    }
  }'
The plan changes immediately in the system. The next charge, on the existing billing date, uses the new plan’s price.
change_mode controls only when the billing cycle starts. With next_billing_date (the default), the existing billing date stays the same. With immediate, the next billing date resets to today plus the new plan’s period.

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