> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Upgrade or downgrade subscriptions

Upgrade or downgrade subscriptions by replacing items on a subscription.

---

Depending on your billing model, you might let customers upgrade or downgrade their plan. This could mean:

- Customers want to change their base plan, for example going from Pro to Enterprise
- Customers want to change their billing frequency, for example going from monthly to annual

{% callout type="note" title="Add items for new users, modules, or other addons" %}
Adding or removing users, modules, one-off fees, or other addons typically involves adding or removing items. For example, you might offer a module called "Advanced Reporting" across all plans. To learn more, see [Add or remove items](https://developer.paddle.com/build/subscriptions/add-remove-products-prices-addons.md)
{% /callout %}

## How it works

In Paddle, there's no rigid hierarchy of products. This means there's no formal distinction between products that you consider base plans and products that you consider addons.

When customers upgrade or downgrade, they're technically replacing items on their subscription. For example, if a customer moves from Pro to Enterprise, you'd remove the Pro product and replace it with the Enterprise one. You can do this in one API call, or on one screen in the Paddle dashboard.

Customers might also say that they're upgrading or downgrading when they change their billing frequency. For example, a customer might say that they'd like to "upgrade to the annual plan." In this case, you'd swap all monthly prices for annual prices.

When you make changes to items, you can determine how Paddle should bill for those changes. This is called [proration](https://developer.paddle.com/concepts/subscriptions/proration.md). Paddle's subscription billing engine calculates proration to the minute, allowing for precise billing.

{% callout type="info" %}
Recurring items on subscription must have the same billing interval. For example, you can't have subscription with some prices that are billed monthly and some products that are billed annually.
{% /callout %}

## Before you begin

{% callout type="info" %}
You can't make changes to a subscription if the next billing period is within 30 minutes, or the subscription status is `past_due`.
{% /callout %}

To upgrade or downgrade a subscription, you'll need to [get the subscription ID](https://developer.paddle.com/api-reference/subscriptions/list-subscriptions.md) for the subscription you want to change.

You can use the `status` query parameter when listing with the value `active` to get a list of active subscriptions.

## Change base plan

Change the base plan when customers want to move from one plan to another. For example, from Pro to Enterprise.

You can choose any [proration billing mode](https://developer.paddle.com/concepts/subscriptions/proration.md).

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

1. Go to **Paddle > Customers**, and find the customer whose subscription you want to change.
2. Find the subscription under the Subscriptions heading and click it.
3. From the subscription overview page, choose Edit subscription
4. Make changes to the items list.
5. To prorate charges, toggle **Charge for what's remaining of the current billing period?** on, then choose how you want to handle proration.
6. Click Continue to review, then Save to proceed.

{% /tab-item %}
{% tab-item title="API" %}

Change the base plan using the API in three steps:

1. **Extract existing items**  
   Get the existing items on the subscription to extract the `price.id` and `quantity` for each item.
2. **Preview change** {% badge label="Optional" variant="outline" /%}  
   Preview how much the customer is going to be charged on a regular basis. Present this to customers if you offer an in-app workflow to upgrade or downgrade.
3. **Update subscription**  
   Send a request to update the subscription with the changes you previewed.

### Extract existing items {% step=true %}

Send a `GET` request to the `/subscriptions/{subscription_id}` endpoint to get the existing items on the subscription. Extract the `price.id` and `quantity` for each item in the `items` array — you'll need these to build your update request.

{% callout type="note" %}
We recommend storing product and price IDs in your database as part of provisioning a subscription. This means you don't need to extract them from the API when updating items on a subscription.
{% /callout %}

{% api-endpoint method="GET" path="/subscriptions/{subscription_id}" href="/api-reference/subscriptions/get-subscription" /%}

### Preview change {% step=true badge="Optional" %}

Send a `PATCH` request to the `/subscriptions/{subscription_id}/preview` endpoint to preview the changes you're making to the subscription.

In your request, build an `items` array. Remove the price ID for the existing base plan, then add existing items that you want to keep, plus the price ID for the new base plan.

Include `proration_billing_mode` to tell Paddle how to bill for the change. For `prorated_immediately` or `full_immediately` on automatically-collected subscriptions, Paddle tries to collect right away. Optionally, include `on_payment_failure` to control payment failure behavior (defaults to `prevent_change`).

Previews include `immediate_transaction`, `next_transaction`, and `recurring_transaction_details`. You should present this to customers if you offer an in-app workflow to upgrade or downgrade.

{% api-endpoint method="PATCH" path="/subscriptions/{subscription_id}/preview" href="/api-reference/subscriptions/preview-subscription" /%}

### Update subscription {% step=true %}

Send a `PATCH` request to the `/subscriptions/{subscription_id}` endpoint to update the subscription.

In your request, include the same body as the preview request.

Paddle updates the subscription.

{% api-example method="PATCH" path="/subscriptions/{subscription_id}" href="/api-reference/subscriptions/update-subscription" %}

```json
{
  "proration_billing_mode": "prorated_immediately",
  "items": [
    {
      "price_id": "pri_01gvne87kv8vbqa9jkfbmgtsed",
      "quantity": 1
    }
  ]
}
```

```json
{
  "data": {
    "id": "sub_01gvne45dvdhg5gdxrz6hh511r",
    "status": "active",
    "customer_id": "ctm_01gvcz30f4d77tfnn60snnyxfd",
    "address_id": "add_01gvczbeepz72bfgsvbcmy1vpg",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2023-03-16T14:45:30.683934Z",
    "updated_at": "2023-03-16T14:45:30.683934Z",
    "started_at": "2023-03-16T14:45:30.683929Z",
    "first_billed_at": "2023-03-16T14:45:30.683929Z",
    "next_billed_at": "2023-04-16T14:45:30.683929Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "manual",
    "billing_details": {
      "enable_checkout": false,
      "purchase_order_number": "",
      "additional_information": "",
      "payment_terms": {
        "frequency": 2,
        "interval": "week"
      }
    },
    "current_billing_period": {
      "starts_at": "2023-03-16T14:45:30.683929Z",
      "ends_at": "2023-04-16T14:45:30.683929Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "recurring_transaction_details": null,
    "next_transaction": null,
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2023-03-16T14:48:08.122643Z",
        "updated_at": "2023-03-16T14:48:08.122643Z",
        "previously_billed_at": null,
        "next_billed_at": "2023-04-16T14:45:30.683929Z",
        "price": {
          "id": "pri_01gvne87kv8vbqa9jkfbmgtsed",
          "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
          "description": "Monthly",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "5000",
            "currency_code": "USD"
          }
        }
      }
    ],
    "custom_data": {},
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01gt25ckjxg1v11jnq9dnrkpfz/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01gt25ckjxg1v11jnq9dnrkpfz/cancel"
    }
  },
  "meta": {
    "request_id": "3fbb2766-5f14-4039-bff8-30cfc9ac0722"
  }
}
```

{% /api-example %}

{% /tab-item %}
{% /tabs %}

## Change billing frequency

Change the billing frequency when customers want to change from paying in one interval to another. For example, from monthly to annually.

When you change billing frequency, you may need to replace multiple items — including addons — so they all have the same frequency. For example, if customers can purchase a Premium Support addon for $200 a month, replace this with a price for Premium Support that bills yearly when moving to an annual base plan.

You can use `prorated_immediately`, `full_immediately`, and `do_not_bill` when [changing billing frequency](https://developer.paddle.com/concepts/subscriptions/proration.md).

{% tabs sync="interaction-preference" %}
{% tab-item title="Dashboard" %}

1. Go to **Paddle > Customers**, and find the customer whose subscription you want to change.
2. Find the subscription under the Subscriptions heading and click it.
3. From the subscription overview page, choose Edit subscription
4. Make changes to the items list.
5. To prorate charges, toggle **Charge for what's remaining of the current billing period?** on, then choose how you want to handle proration.
6. Click Continue to review, then Save to proceed.

{% /tab-item %}
{% tab-item title="API" %}

Change billing frequency using the API in three steps:

1. **Extract existing items**  
   Get the existing items on the subscription to extract the `price.id` and `quantity` for each item.
2. **Preview change** {% badge label="Optional" variant="outline" /%}  
   Preview how much the customer is going to be charged on a regular basis. Present this to customers if you offer an in-app workflow to upgrade or downgrade.
3. **Update subscription**  
   Send a request to update the subscription with the changes you previewed.

### Extract existing items {% step=true stepReset=true %}

Send a `GET` request to the `/subscriptions/{subscription_id}` endpoint to get the existing items on the subscription. Extract the `price.id` and `quantity` for each item in the `items` array — you'll need these to build your update request.

{% callout type="note" %}
We recommend storing product and price IDs in your database as part of provisioning a subscription. This means you don't need to extract them from the API when updating items on a subscription.
{% /callout %}

{% api-endpoint method="GET" path="/subscriptions/{subscription_id}" href="/api-reference/subscriptions/get-subscription" /%}

### Preview change {% step=true badge="Optional" %}

Send a `PATCH` request to the `/subscriptions/{subscription_id}/preview` endpoint to preview the changes you're making to the subscription.

In your request, build an `items` array. Remove the price ID for the existing base plan and any recurring addons, then add existing items that you want to keep (like one-time charges), plus the price ID for the new base plan and any new addons.

Include `proration_billing_mode` to tell Paddle how to bill for the change. Only `prorated_immediately`, `full_immediately`, and `do_not_bill` are allowed [when changing billing frequency](https://developer.paddle.com/concepts/subscriptions/proration.md). Optionally, include `on_payment_failure` to control payment failure behavior (defaults to `prevent_change`).

Previews include `immediate_transaction`, `next_transaction`, and `recurring_transaction_details`. You should present this to customers if you offer an in-app workflow to upgrade or downgrade.

{% api-endpoint method="PATCH" path="/subscriptions/{subscription_id}/preview" href="/api-reference/subscriptions/preview-subscription" /%}

### Update subscription {% step=true %}

Send a `PATCH` request to the `/subscriptions/{subscription_id}` endpoint to update the subscription.

In your request, include the same body as the preview request.

Paddle updates the subscription.

{% api-example method="PATCH" path="/subscriptions/{subscription_id}" href="/api-reference/subscriptions/update-subscription" %}

```json
{
  "proration_billing_mode": "prorated_immediately",
  "items": [
    {
      "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea",
      "quantity": 1
    }
  ]
}
```

```json
{
  "data": {
    "id": "sub_01gvne45dvdhg5gdxrz6hh511r",
    "status": "active",
    "customer_id": "ctm_01gvcz30f4d77tfnn60snnyxfd",
    "address_id": "add_01gvczbeepz72bfgsvbcmy1vpg",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2023-03-16T14:45:30.683934Z",
    "updated_at": "2023-03-16T14:45:30.683934Z",
    "started_at": "2023-03-16T14:45:30.683929Z",
    "first_billed_at": "2023-03-16T14:45:30.683929Z",
    "next_billed_at": "2024-03-16T14:45:30.683929Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "manual",
    "billing_details": {
      "enable_checkout": false,
      "purchase_order_number": "",
      "additional_information": "",
      "payment_terms": {
        "frequency": 2,
        "interval": "week"
      }
    },
    "current_billing_period": {
      "starts_at": "2023-03-16T14:45:30.683929Z",
      "ends_at": "2024-03-16T14:45:30.683929Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "year"
    },
    "recurring_transaction_details": null,
    "next_transaction": null,
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2023-03-16T14:48:08.122643Z",
        "updated_at": "2023-03-16T14:48:08.122643Z",
        "previously_billed_at": null,
        "next_billed_at": "2024-03-16T14:45:30.683929Z",
        "price": {
          "id": "pri_01gsz91wy9k1yn7kx82aafwvea",
          "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
          "description": "Annual",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "year"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "50000",
            "currency_code": "USD"
          }
        }
      }
    ],
    "custom_data": {},
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01gt25ckjxg1v11jnq9dnrkpfz/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01gt25ckjxg1v11jnq9dnrkpfz/cancel"
    }
  },
  "meta": {
    "request_id": "3fbb2766-5f14-4039-bff8-30cfc9ac0722"
  }
}
```

{% /api-example %}

{% /tab-item %}
{% /tabs %}