---
api: 'Merchant API'
---

# Change a subscription plan

Schedule a plan change for a subscription. The change is applied at the end of the current billing cycle.

### Use cases

- **Plan upgrades:** Moving a customer to a higher-tier plan with more features or capacity.
- **Plan downgrades:** Moving a customer to a lower-tier plan that better fits their usage and budget.
- **Customer requests:** Accommodating a customer's request to switch to a different plan variation.

### How it works

When you schedule a plan change, the subscription continues operating under its current plan variation until the current billing cycle ends. At that point, the next cycle is created under the new plan variation.

- **Scheduled change:** The plan change is scheduled to take effect `at_cycle_end`. The current cycle completes normally, and the new plan variation applies starting from the next cycle.
- **Plan variation phases:** Some plan variations are divided into phases - distinct pricing or duration periods within a single variation. If the target plan variation has multiple phases, use `plan_variation_phase_id` to specify which phase to start from. If omitted, the change starts from the first phase.
- **Trial periods:** If the target plan variation includes a trial period, it is skipped when changing plans. Trial periods only apply when a subscription is first created.
- **Subsequent cycles:** After the transition, future cycles follow the cadence and pricing defined by the new plan variation.

## Endpoint

POST `/api/subscriptions/{subscription_id}/change-plan`

## Request body

### Attributes

- `plan_variation_id` (string)
    Unique identifier for the subscription plan variation.
- `plan_variation_phase_id` (string, optional)
    Unique identifier for the subscription plan phase.
- `scheduled` (enum)
    When the plan change should take effect.
    
    | Value | Description |
    | ----- | ----------- |
    | `at_cycle_end` | The change is applied at the end of the current billing cycle. |
    Possible enum values:

    - `at_cycle_end`
- `reason` (enum, optional)
    The reason for the scheduled action. This field is informational and does not affect how the action is processed.
    
    | Value | Description |
    | ----- | ----------- |
    | `customer_request` | The action was requested by the customer. |
    | `merchant_request` | The action was initiated by the merchant. |
    Possible enum values:

    - `customer_request`
    - `merchant_request`

## Returns

### 204

Plan change scheduled successfully

## Error responses

| HTTP status code | Description |
| --- | --- |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Subscription not found |
| 422 | Unprocessable entity |