Change Subscription Plan

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…	Approach	Payment
Charge the prorated difference now	Immediate Payment	Charged now
Change the plan now without charging	Patch with `immediate`	Next billing date resets to today
Change the plan at the current billing date	Patch with `next_billing_date`	Existing billing date

Change With Immediate Payment

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

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" }
  }'

Show Proration modes

Mode	Behavior
`prorated_immediately` (default)	Charge difference based on remaining time
`full_immediately`	Charge full new plan price

Proration example: Customer on

30/week plan, 3 of 7 days used, upgrades to

100/month: 100 − 30 × (3 ÷ 7) = $87.14For downgrades, negative amounts floor at $0 (no credit issued).

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.

Introduction

Use Cases

Platform

Payments

Fraud Prevention

Advanced Features

Developers

Choose Your Approach

Change With Immediate Payment

Change Without a Charge

Schedule Plan Change

Silent Plan Change (No UI)

​Choose Your Approach

​Change With Immediate Payment

​Change Without a Charge

​Schedule Plan Change

​Silent Plan Change (No UI)

Choose Your Approach

Change With Immediate Payment

Change Without a Charge

Schedule Plan Change

Silent Plan Change (No UI)