> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paynext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Change Subscription Plan

> Upgrade or downgrade a customer's subscription—charge immediately or schedule for next billing cycle.

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](#change-with-immediate-payment)     | Charged now                       |
| Change the plan now without charging        | [Patch with `immediate`](#change-without-a-charge)      | Next billing date resets to today |
| Change the plan at the current billing date | [Patch with `next_billing_date`](#schedule-plan-change) | Existing billing date             |

## Change With Immediate Payment

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

<Steps>
  <Step title="Create a client session">
    Include the customer, subscription, and new plan:

    ```bash cURL theme={"system"}
    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" }
      }'
    ```

    <Expandable title="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.14`

      For downgrades, negative amounts floor at \$0 (no credit issued).
    </Expandable>
  </Step>

  <Step title="Mount the SDK">
    Display checkout with the customer's saved payment method:

    ```javascript theme={"system"}
    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
      }
    })
    ```
  </Step>
</Steps>

**Outcomes:**

* **Success**: Plan updates immediately, billing cycle resets to today
* **Failure**: Subscription stays on old plan; customer can retry with a different card

<Warning>
  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.
</Warning>

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

```bash cURL theme={"system"}
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`.

```bash cURL theme={"system"}
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.

<Note>
  `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.
</Note>

## Silent Plan Change (No UI)

To change plans without showing checkout, use the [API-only approach](/guides/use-cases/charge-returning-customers#api-only-charges). This charges the customer's saved payment method directly.

<Warning>
  Background charges have no card update UI. If payment fails, you must notify the customer separately.
</Warning>