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

# Add or remove items from a subscription

Add items to subscriptions when customers want to take additional users, modules, or other kinds of recurring addons. Remove items when customers want to change or cancel them.

---

Paddle supports multi-product subscriptions, letting you build complex pricing models. Add or remove items from a subscription to make changes to customer plans.

Add or remove items from a subscription when:

- Customers pay per user, and they add users to their subscription
- A customer wants to stop paying for ("cancel") an additional recurring product, like a reporting module
- You have a tiered or volume pricing model and need to set the tier to bill for

You can add items, remove items, and change quantities in the same request. We've split them into separate examples here for simplicity.

## How it works

You might have a subscription billing model that's made up of multiple components. For example, you might offer a base plan and additional modules or users.

In Paddle, you don't need to create multiple subscriptions for multiple products. Each subscription holds an `items` list that can contain multiple products. When a customer does something like takes on a new module or decreases their user count, you can make changes to the items list on their subscription bill for the changes.

Keep in mind that customers might say:

- They're "canceling" a product, like a module or other recurring addon, when they'd like to remove it. Canceling items doesn't [cancel a subscription entirely](https://developer.paddle.com/build/subscriptions/cancel-subscriptions.md).
- They're "subscribing" or "upgrading" when they add a product or change quantities. You don't need to create a new subscription to bill for new products.

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

### Proration

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.

Before you add or remove items on a subscription, you can preview the changes first. This lets you see prorated charges for any changes that you're making before charging for them. You might present this to the customer in your frontend.

### Related subscription changes

Adding or removing items is typically used when you want to make changes to recurring addons, like optional modules or seats.

Depending on what you're looking to do, you might also like to:

- [**Replace items to upgrade or downgrade a subscription**](https://developer.paddle.com/build/subscriptions/replace-products-prices-upgrade-downgrade.md)  
  Upgrading or downgrading a subscription plan typically involves replacing products. For example, you might replace a "Starter plan" product with a "Premium plan" product to upgrade.
- [**Create one-time charges for non-recurring items**](https://developer.paddle.com/build/subscriptions/bill-add-one-time-charge.md)  
  One-time charges aren't included in the `items` list for a subscription, since they aren't recurring. Create a one-time charge instead. For example, you might bill for an "Out of hours support incident" as and when it happens.

## 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 add or remove items from 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 `trialing` to get a list of subscriptions in trial.

## Add items to a subscription

{% 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 %}

Add recurring items to subscriptions when customers want to take additional modules or services. They might call this "upgrading."

You can use 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**.
2. Find the customer whose subscription you want to add an item to, then click them to open the customer page.
3. Find the subscription that you want to change under the Subscriptions heading and click it to open the subscription page.
4. From the subscription overview page, click Edit subscription
5. Click the Add line item link to add items new items to the items list. Choose a product, related price, and quantity for each item.
6. Choose a product, related price, and quantity for each item.
7. Choose whether to bill for the prorated amount or full amount, and when it should be charged.
8. If you don't want to bill for these changes at all, toggle **Charge for what's remaining of the current billing period?** off.
9. Click Continue to review.
10. Review the summary of your changes.
11. Click Save to apply your changes.

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

Add items to a subscription 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 update items.
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, include an an `items` array with an object containing a `price_id` and `quantity` for each item you want on the subscription — include existing items you want to keep, plus any new ones. Omit `quantity` for existing items where you're not changing the amount.

Include `proration_billing_mode` to tell Paddle how to bill for the changes. 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`).

This example adds two new items with `quantity: 1` each. The existing item has no `quantity` so it stays unchanged. `proration_billing_mode` is `prorated_next_billing_period`.

Previews include `immediate_transaction`, `next_transaction`, and `recurring_transaction_details`. In this example, `proration_billing_mode` is `prorated_next_billing_period`, so `immediate_transaction` is `null` and proration is charged on the next renewal.

You should present this to customers if you offer an in-app workflow to update items.

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

```json
{
  "proration_billing_mode": "prorated_next_billing_period",
  "items": [
    {
      "price_id": "pri_01gsz95g2zrkagg294kpstx54r",
      "quantity": 1
    },
    {
      "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
      "quantity": 1
    },
    {
      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke"
    }
  ]
}
```

```json
{
  "data": {
    "status": "active",
    "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
    "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2023-06-22T08:25:14.287455Z",
    "updated_at": "2023-06-22T08:30:27.133418Z",
    "started_at": "2023-06-22T08:25:12.565118Z",
    "first_billed_at": "2023-06-22T08:25:12.565118Z",
    "next_billed_at": "2023-07-22T08:25:12.565118Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2023-06-22T08:25:12.565118Z",
      "ends_at": "2023-07-22T08:25:12.565118Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "recurring_transaction_details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "68500",
            "discount": "0",
            "tax": "6078",
            "total": "74578"
          }
        }
      ],
      "totals": {
        "subtotal": "68500",
        "tax": "6078",
        "discount": "0",
        "total": "74578",
        "fee": null,
        "credit": "0",
        "balance": "74578",
        "grand_total": "74578",
        "earnings": null,
        "currency_code": "USD"
      },
      "line_items": [
        {
          "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "quantity": 10,
          "totals": {
            "subtotal": "30000",
            "tax": "2662",
            "discount": "0",
            "total": "32662"
          },
          "product": {
            "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
            "name": "ChatApp Pro",
            "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "3000",
            "discount": "0",
            "tax": "266",
            "total": "3266"
          }
        },
        {
          "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "quantity": 1,
          "totals": {
            "subtotal": "10000",
            "tax": "887",
            "discount": "0",
            "total": "10887"
          },
          "product": {
            "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
            "name": "Voice rooms addon",
            "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "10000",
            "discount": "0",
            "tax": "887",
            "total": "10887"
          }
        },
        {
          "price_id": "pri_01gsz95g2zrkagg294kpstx54r",
          "quantity": 1,
          "totals": {
            "subtotal": "28500",
            "tax": "2529",
            "discount": "0",
            "total": "31029"
          },
          "product": {
            "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
            "name": "Reporting module",
            "description": "Get access to comprehensive reports and customizable analytics dashboards.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/SW3OevDQ92dUHSkN5a2x_icon3.png",
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "28500",
            "discount": "0",
            "tax": "2529",
            "total": "31029"
          }
        }
      ]
    },
    "next_transaction": {
      "billing_period": {
        "starts_at": "2023-07-22T08:25:12.565118Z",
        "ends_at": "2023-08-22T08:25:12.565118Z"
      },
      "details": {
        "tax_rates_used": [
          {
            "tax_rate": "0.08875",
            "totals": {
              "subtotal": "106996",
              "discount": "0",
              "tax": "9494",
              "total": "116490"
            }
          }
        ],
        "totals": {
          "subtotal": "106996",
          "tax": "9494",
          "discount": "0",
          "total": "116490",
          "fee": null,
          "credit": "0",
          "balance": "116490",
          "grand_total": "116490",
          "earnings": null,
          "currency_code": "USD"
        },
        "line_items": [
          {
            "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
            "quantity": 10,
            "totals": {
              "subtotal": "30000",
              "tax": "2662",
              "discount": "0",
              "total": "32662"
            },
            "product": {
              "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
              "name": "ChatApp Pro",
              "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.",
              "tax_category": "standard",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
              "status": "active"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "3000",
              "discount": "0",
              "tax": "266",
              "total": "3266"
            }
          },
          {
            "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
            "quantity": 1,
            "totals": {
              "subtotal": "10000",
              "tax": "887",
              "discount": "0",
              "total": "10887"
            },
            "product": {
              "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
              "name": "Voice rooms addon",
              "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
              "tax_category": "standard",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
              "status": "active"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "10000",
              "discount": "0",
              "tax": "887",
              "total": "10887"
            }
          },
          {
            "price_id": "pri_01gsz95g2zrkagg294kpstx54r",
            "quantity": 1,
            "totals": {
              "subtotal": "28500",
              "tax": "2529",
              "discount": "0",
              "total": "31029"
            },
            "product": {
              "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
              "name": "Reporting module",
              "description": "Get access to comprehensive reports and customizable analytics dashboards.",
              "tax_category": "standard",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/SW3OevDQ92dUHSkN5a2x_icon3.png",
              "status": "active"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "28500",
              "discount": "0",
              "tax": "2529",
              "total": "31029"
            }
          },
          {
            "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
            "quantity": 1,
            "totals": {
              "subtotal": "9999",
              "tax": "887",
              "discount": "0",
              "total": "10886"
            },
            "product": {
              "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
              "name": "Voice rooms addon",
              "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
              "tax_category": "standard",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
              "status": "active"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "9999",
              "discount": "0",
              "tax": "887",
              "total": "10886"
            },
            "proration": {
              "rate": "0.99988",
              "billing_period": {
                "starts_at": "2023-06-22T08:30:27.123319Z",
                "ends_at": "2023-07-22T08:25:12.565118Z"
              }
            }
          },
          {
            "price_id": "pri_01gsz95g2zrkagg294kpstx54r",
            "quantity": 1,
            "totals": {
              "subtotal": "28497",
              "tax": "2529",
              "discount": "0",
              "total": "31026"
            },
            "product": {
              "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
              "name": "Reporting module",
              "description": "Get access to comprehensive reports and customizable analytics dashboards.",
              "tax_category": "standard",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/SW3OevDQ92dUHSkN5a2x_icon3.png",
              "status": "active"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "28497",
              "discount": "0",
              "tax": "2529",
              "total": "31026"
            },
            "proration": {
              "rate": "0.99988",
              "billing_period": {
                "starts_at": "2023-06-22T08:30:27.125971Z",
                "ends_at": "2023-07-22T08:25:12.565118Z"
              }
            }
          }
        ]
      },
      "adjustments": []
    },
    "immediate_transaction": null,
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 10,
        "recurring": true,
        "created_at": "2023-06-22T08:25:14.287456Z",
        "updated_at": "2023-06-22T08:25:14.287456Z",
        "previously_billed_at": "2023-06-22T08:25:12.565118Z",
        "next_billed_at": "2023-07-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "description": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3266",
            "currency_code": "USD"
          }
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2023-06-22T08:30:26.695165Z",
        "updated_at": "2023-06-22T08:30:26.695165Z",
        "previously_billed_at": null,
        "next_billed_at": "2023-07-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "description": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10887",
            "currency_code": "USD"
          }
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2023-06-22T08:30:26.695175Z",
        "updated_at": "2023-06-22T08:30:26.695175Z",
        "previously_billed_at": null,
        "next_billed_at": "2023-07-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01gsz95g2zrkagg294kpstx54r",
          "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "description": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "31029",
            "currency_code": "USD"
          }
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/cancel"
    },
    "discount": null
  },
  "meta": {
    "request_id": "814c42dc-eb30-4840-a637-29b6df8e9bac"
  }
}
```

{% /api-example %}

### 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_next_billing_period",
  "items": [
    {
      "price_id": "pri_01gsz95g2zrkagg294kpstx54r",
      "quantity": 1
    },
    {
      "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
      "quantity": 1
    },
    {
      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke"
    }
  ]
}
```

```json
{
  "data": {
    "id": "sub_01h3h3a9sfpr5syq38tq0sd4sp",
    "status": "active",
    "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
    "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2023-06-22T08:25:14.287455Z",
    "updated_at": "2023-06-22T08:40:46.295638Z",
    "started_at": "2023-06-22T08:25:12.565118Z",
    "first_billed_at": "2023-06-22T08:25:12.565118Z",
    "next_billed_at": "2023-07-22T08:25:12.565118Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2023-06-22T08:25:12.565118Z",
      "ends_at": "2023-07-22T08:25:12.565118Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 10,
        "recurring": true,
        "created_at": "2023-06-22T08:25:14.287456Z",
        "updated_at": "2023-06-22T08:25:14.287456Z",
        "previously_billed_at": "2023-06-22T08:25:12.565118Z",
        "next_billed_at": "2023-07-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "description": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3266",
            "currency_code": "USD"
          }
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2023-06-22T08:40:45.808402Z",
        "updated_at": "2023-06-22T08:40:45.808402Z",
        "previously_billed_at": null,
        "next_billed_at": "2023-07-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "description": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10887",
            "currency_code": "USD"
          }
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2023-06-22T08:40:45.808418Z",
        "updated_at": "2023-06-22T08:40:45.808418Z",
        "previously_billed_at": null,
        "next_billed_at": "2023-07-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01gsz95g2zrkagg294kpstx54r",
          "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "description": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "31029",
            "currency_code": "USD"
          }
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/cancel"
    },
    "discount": null
  },
  "meta": {
    "request_id": "1ce4f946-eeb6-4369-a170-a9c79a88455c"
  }
}
```

{% /api-example %}

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

## Remove items from a subscription

Remove items from subscriptions when customers no longer want additional modules or other addons. They might call this "canceling" those modules or addons.

Depending on your pricing model, you might also do this as part of [an upgrade or downgrade workflow](https://developer.paddle.com/build/subscriptions/replace-products-prices-upgrade-downgrade.md), too. For example, some items might be incompatible with entry-level plans, or might be included in higher-level plans.

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**.
2. Find the customer whose subscription you want to remove an item from, then click them to open the customer page.
3. Find the subscription that you want to change under the Subscriptions heading and click it to open the subscription page.
4. From the subscription overview page, click Edit subscription
5. Click the  button next to an item in the list, then choose Remove item from the menu.
6. Choose whether to credit the prorated or full amount, and when to issue it.
7. If you don't want to credit for these changes at all, toggle **Issue credit for what's remaining of the current billing period?** off.
8. Click Continue to review.
9. Review the summary of your changes.
10. Click Save to apply your changes.

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

Remove items from a subscription 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 update items.
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" %}

{% callout type="info" %}
Subscriptions must have at least one item. Consider [canceling a subscription entirely](https://developer.paddle.com/build/subscriptions/cancel-subscriptions.md), or [pausing](https://developer.paddle.com/build/subscriptions/pause-subscriptions.md) to stop billing temporarily.
{% /callout %}

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

Include an `items` array with price IDs and quantities for items you want to **keep** — omit any items you want to remove.

Include `proration_billing_mode` to determine how to credit the removed items. Optionally, include `on_payment_failure` to control payment failure behavior (defaults to `prevent_change`).

This example keeps two items and removes the third by omitting it. `proration_billing_mode` is `prorated_next_billing_period`, so Paddle credits the removed item on the next renewal.

Previews include `immediate_transaction`, `next_transaction`, and `recurring_transaction_details`. In this example, `proration_billing_mode` is `prorated_next_billing_period`, so `immediate_transaction` is `null` and Paddle calculates a credit deducted from the next renewal.

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

```json
{
  "proration_billing_mode": "prorated_next_billing_period",
  "items": [
    {
      "price_id": "pri_01h1vjfevh5etwq3rb416a23h2"
    },
    {
      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke"
    }
  ]
}
```

```json
{
  "data": {
    "status": "active",
    "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
    "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2023-06-22T08:25:14.287455Z",
    "updated_at": "2023-07-22T09:25:32.374176Z",
    "started_at": "2023-06-22T08:25:12.565118Z",
    "first_billed_at": "2023-06-22T08:25:12.565118Z",
    "next_billed_at": "2023-08-22T08:25:12.565118Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2023-07-22T08:25:12.565118Z",
      "ends_at": "2023-08-22T08:25:12.565118Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "recurring_transaction_details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "40000",
            "discount": "0",
            "tax": "3549",
            "total": "43549"
          }
        }
      ],
      "totals": {
        "subtotal": "40000",
        "tax": "3549",
        "discount": "0",
        "total": "43549",
        "fee": null,
        "credit": "0",
        "balance": "43549",
        "grand_total": "43549",
        "earnings": null,
        "currency_code": "USD"
      },
      "line_items": [
        {
          "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "quantity": 10,
          "totals": {
            "subtotal": "30000",
            "tax": "2662",
            "discount": "0",
            "total": "32662"
          },
          "product": {
            "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
            "name": "ChatApp Pro",
            "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "3000",
            "discount": "0",
            "tax": "266",
            "total": "3266"
          }
        },
        {
          "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "quantity": 1,
          "totals": {
            "subtotal": "10000",
            "tax": "887",
            "discount": "0",
            "total": "10887"
          },
          "product": {
            "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
            "name": "Voice rooms addon",
            "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "10000",
            "discount": "0",
            "tax": "887",
            "total": "10887"
          }
        }
      ]
    },
    "next_transaction": {
      "billing_period": {
        "starts_at": "2023-08-22T08:25:12.565118Z",
        "ends_at": "2023-09-22T08:25:12.565118Z"
      },
      "details": {
        "tax_rates_used": [
          {
            "tax_rate": "0.08875",
            "totals": {
              "subtotal": "40000",
              "discount": "0",
              "tax": "3549",
              "total": "43549"
            }
          }
        ],
        "totals": {
          "subtotal": "40000",
          "tax": "3549",
          "discount": "0",
          "total": "43549",
          "fee": null,
          "credit": "30987",
          "balance": "12562",
          "grand_total": "12562",
          "earnings": null,
          "currency_code": "USD"
        },
        "line_items": [
          {
            "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
            "quantity": 10,
            "totals": {
              "subtotal": "30000",
              "tax": "2662",
              "discount": "0",
              "total": "32662"
            },
            "product": {
              "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
              "name": "ChatApp Pro",
              "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.",
              "tax_category": "standard",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
              "status": "active"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "3000",
              "discount": "0",
              "tax": "266",
              "total": "3266"
            }
          },
          {
            "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
            "quantity": 1,
            "totals": {
              "subtotal": "10000",
              "tax": "887",
              "discount": "0",
              "total": "10887"
            },
            "product": {
              "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
              "name": "Voice rooms addon",
              "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
              "tax_category": "standard",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
              "status": "active"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "10000",
              "discount": "0",
              "tax": "887",
              "total": "10887"
            }
          }
        ]
      },
      "adjustments": [
        {
          "transaction_id": "txn_01h3h4j5hj2cfzme5pscbvapb5",
          "items": [
            {
              "item_id": "txnitm_01h3h4j5zymz2d2sncvmk78ns4",
              "type": "proration",
              "amount": "30987",
              "proration": {
                "rate": "0.99866",
                "billing_period": {
                  "starts_at": "2023-07-22T09:25:32.373183Z",
                  "ends_at": "2023-08-22T08:25:12.565118Z"
                }
              },
              "totals": {
                "subtotal": "28461",
                "tax": "2526",
                "total": "30987"
              }
            }
          ],
          "totals": {
            "subtotal": "28461",
            "tax": "2526",
            "total": "30987",
            "fee": "1563",
            "earnings": "26898",
            "currency_code": "USD"
          }
        }
      ]
    },
    "immediate_transaction": null,
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 10,
        "recurring": true,
        "created_at": "2023-06-22T08:25:14.287456Z",
        "updated_at": "2023-07-22T08:25:36.112473Z",
        "previously_billed_at": "2023-07-22T08:25:12.565118Z",
        "next_billed_at": "2023-08-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "description": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3266",
            "currency_code": "USD"
          }
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2023-06-22T08:40:45.808402Z",
        "updated_at": "2023-07-22T08:25:36.114303Z",
        "previously_billed_at": "2023-07-22T08:25:12.565118Z",
        "next_billed_at": "2023-08-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "description": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10887",
            "currency_code": "USD"
          }
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/cancel"
    },
    "discount": null
  },
  "meta": {
    "request_id": "912bdd81-ee77-4c3c-b666-3d03cc765c0c"
  }
}
```

{% /api-example %}

### 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_next_billing_period",
  "items": [
    {
      "price_id": "pri_01h1vjfevh5etwq3rb416a23h2"
    },
    {
      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke"
    }
  ]
}
```

```json
{
  "data": {
    "id": "sub_01h3h3a9sfpr5syq38tq0sd4sp",
    "status": "active",
    "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
    "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2023-06-22T08:25:14.287455Z",
    "updated_at": "2023-07-22T09:33:24.427246Z",
    "started_at": "2023-06-22T08:25:12.565118Z",
    "first_billed_at": "2023-06-22T08:25:12.565118Z",
    "next_billed_at": "2023-08-22T08:25:12.565118Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2023-07-22T08:25:12.565118Z",
      "ends_at": "2023-08-22T08:25:12.565118Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 10,
        "recurring": true,
        "created_at": "2023-06-22T08:25:14.287456Z",
        "updated_at": "2023-07-22T08:25:36.112473Z",
        "previously_billed_at": "2023-07-22T08:25:12.565118Z",
        "next_billed_at": "2023-08-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "description": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3266",
            "currency_code": "USD"
          }
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2023-06-22T08:40:45.808402Z",
        "updated_at": "2023-07-22T08:25:36.114303Z",
        "previously_billed_at": "2023-07-22T08:25:12.565118Z",
        "next_billed_at": "2023-08-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "description": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10887",
            "currency_code": "USD"
          }
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/cancel"
    },
    "discount": null
  },
  "meta": {
    "request_id": "fe11c394-3431-477f-a3ac-a63da6704545"
  }
}
```

{% /api-example %}

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

## Change quantities

Change quantities when customers want to increase or decrease the number of units of an item that they pay for. You might change quantities if your pricing is per user or seat. They might call it "upgrading" when increasing units, and "downgrading" when decreasing units.

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**.
2. Find the customer whose subscription you want to change quantities for items on, then click them to open the customer page.
3. Find the subscription that you want to change under the Subscriptions heading and click it to open the subscription page.
4. From the subscription overview page, click Edit subscription
5. Make changes to quantities in the items list.
6. Depending on the changes you made, choose to either credit or charge for the prorated or full amount, and charge or issue for it now or later.
7. If you don't want these changes to be charged or credited at all, toggle the proration option off.
8. Click Continue to review.
9. Review the summary of your changes.
10. Click Save to apply your changes.

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

Change quantities on a subscription 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 update items.
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.

Include an `items` array with the same price IDs and updated quantities. You can omit `quantity` for items you're not changing.

Include `proration_billing_mode` to tell Paddle how to bill for the quantity changes. 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`).

This example increases seats from `10` to `30`. The voice rooms addon has no `quantity` so it stays unchanged.

Previews include `immediate_transaction`, `next_transaction`, and `recurring_transaction_details`. In this example, `proration_billing_mode` is `prorated_immediately`, so Paddle calculates and charges proration right away, detailed in `immediate_transaction`.

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

```json
{
  "proration_billing_mode": "prorated_immediately",
  "items": [
    {
      "price_id": "pri_01h1vjfevh5etwq3rb416a23h2"
    },
    {
      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
      "quantity": 30
    }
  ]
}
```

```json
{
  "data": {
    "status": "active",
    "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
    "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2023-06-22T08:25:14.287455Z",
    "updated_at": "2023-08-22T08:28:30.220384Z",
    "started_at": "2023-06-22T08:25:12.565118Z",
    "first_billed_at": "2023-06-22T08:25:12.565118Z",
    "next_billed_at": "2023-09-22T08:25:12.565118Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2023-08-22T08:25:12.565118Z",
      "ends_at": "2023-09-22T08:25:12.565118Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "recurring_transaction_details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "100000",
            "discount": "0",
            "tax": "8874",
            "total": "108874"
          }
        }
      ],
      "totals": {
        "subtotal": "100000",
        "tax": "8874",
        "discount": "0",
        "total": "108874",
        "fee": null,
        "credit": "0",
        "balance": "108874",
        "grand_total": "108874",
        "earnings": null,
        "currency_code": "USD"
      },
      "line_items": [
        {
          "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "quantity": 30,
          "totals": {
            "subtotal": "90000",
            "tax": "7987",
            "discount": "0",
            "total": "97987"
          },
          "product": {
            "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
            "name": "ChatApp Pro",
            "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "3000",
            "discount": "0",
            "tax": "266",
            "total": "3266"
          }
        },
        {
          "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "quantity": 1,
          "totals": {
            "subtotal": "10000",
            "tax": "887",
            "discount": "0",
            "total": "10887"
          },
          "product": {
            "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
            "name": "Voice rooms addon",
            "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
            "tax_category": "standard",
            "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
            "status": "active"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "10000",
            "discount": "0",
            "tax": "887",
            "total": "10887"
          }
        }
      ]
    },
    "next_transaction": {
      "billing_period": {
        "starts_at": "2023-09-22T08:25:12.565118Z",
        "ends_at": "2023-10-22T08:25:12.565118Z"
      },
      "details": {
        "tax_rates_used": [
          {
            "tax_rate": "0.08875",
            "totals": {
              "subtotal": "100000",
              "discount": "0",
              "tax": "8874",
              "total": "108874"
            }
          }
        ],
        "totals": {
          "subtotal": "100000",
          "tax": "8874",
          "discount": "0",
          "total": "108874",
          "fee": null,
          "credit": "0",
          "balance": "108874",
          "grand_total": "108874",
          "earnings": null,
          "currency_code": "USD"
        },
        "line_items": [
          {
            "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
            "quantity": 30,
            "totals": {
              "subtotal": "90000",
              "tax": "7987",
              "discount": "0",
              "total": "97987"
            },
            "product": {
              "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
              "name": "ChatApp Pro",
              "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.",
              "tax_category": "standard",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
              "status": "active"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "3000",
              "discount": "0",
              "tax": "266",
              "total": "3266"
            }
          },
          {
            "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
            "quantity": 1,
            "totals": {
              "subtotal": "10000",
              "tax": "887",
              "discount": "0",
              "total": "10887"
            },
            "product": {
              "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
              "name": "Voice rooms addon",
              "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.",
              "tax_category": "standard",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png",
              "status": "active"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "10000",
              "discount": "0",
              "tax": "887",
              "total": "10887"
            }
          }
        ]
      },
      "adjustments": []
    },
    "immediate_transaction": {
      "billing_period": {
        "starts_at": "2023-08-22T08:28:31.678675268Z",
        "ends_at": "2023-09-22T08:25:12.565118Z"
      },
      "details": {
        "tax_rates_used": [
          {
            "tax_rate": "0.08875",
            "totals": {
              "subtotal": "89994",
              "discount": "0",
              "tax": "7987",
              "total": "97981"
            }
          }
        ],
        "totals": {
          "subtotal": "89994",
          "tax": "7987",
          "discount": "0",
          "total": "97981",
          "fee": null,
          "credit": "32660",
          "balance": "65321",
          "grand_total": "65321",
          "earnings": null,
          "currency_code": "USD"
        },
        "line_items": [
          {
            "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
            "quantity": 30,
            "totals": {
              "subtotal": "89994",
              "tax": "7987",
              "discount": "0",
              "total": "97981"
            },
            "product": {
              "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
              "name": "ChatApp Pro",
              "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.",
              "tax_category": "standard",
              "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png",
              "status": "active"
            },
            "tax_rate": "0.08875",
            "unit_totals": {
              "subtotal": "3000",
              "discount": "0",
              "tax": "266",
              "total": "3266"
            },
            "proration": {
              "rate": "0.99993",
              "billing_period": {
                "starts_at": "2023-08-22T08:28:30.2190671Z",
                "ends_at": "2023-09-22T08:25:12.565118Z"
              }
            }
          }
        ]
      },
      "adjustments": [
        {
          "transaction_id": "txn_01h3h8qvbbgsvvakck3w432t7p",
          "items": [
            {
              "item_id": "txnitm_01h3h8qvs7cmyyb9fs92hqbzdh",
              "type": "proration",
              "amount": "32660",
              "proration": {
                "rate": "0.99993",
                "billing_period": {
                  "starts_at": "2023-08-22T08:28:30.217459Z",
                  "ends_at": "2023-09-22T08:25:12.565118Z"
                }
              },
              "totals": {
                "subtotal": "29998",
                "tax": "2662",
                "total": "32660"
              }
            }
          ],
          "totals": {
            "subtotal": "29998",
            "tax": "2662",
            "total": "32660",
            "fee": "1670",
            "earnings": "28328",
            "currency_code": "USD"
          }
        }
      ]
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 30,
        "recurring": true,
        "created_at": "2023-06-22T08:25:14.287456Z",
        "updated_at": "2023-08-22T08:28:30.210601Z",
        "previously_billed_at": "2023-08-22T08:25:12.565118Z",
        "next_billed_at": "2023-09-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "description": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3266",
            "currency_code": "USD"
          }
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2023-06-22T08:40:45.808402Z",
        "updated_at": "2023-08-22T08:26:06.361047Z",
        "previously_billed_at": "2023-08-22T08:25:12.565118Z",
        "next_billed_at": "2023-09-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "description": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10887",
            "currency_code": "USD"
          }
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/cancel"
    },
    "discount": null
  },
  "meta": {
    "request_id": "16c114e9-1966-41fd-b64c-44d3901ca0c2"
  }
}
```

{% /api-example %}

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

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

```json
{
  "proration_billing_mode": "prorated_immediately",
  "items": [
    {
      "price_id": "pri_01h1vjfevh5etwq3rb416a23h2"
    },
    {
      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
      "quantity": 30
    }
  ]
}
```

```json
{
  "data": {
    "id": "sub_01h3h3a9sfpr5syq38tq0sd4sp",
    "status": "active",
    "customer_id": "ctm_01h3h38xn5c2701bb5eecy9m6a",
    "address_id": "add_01h3h38xqmv1xy0tjsnj0g1ke5",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2023-06-22T08:25:14.287455Z",
    "updated_at": "2023-08-22T08:32:24.559129Z",
    "started_at": "2023-06-22T08:25:12.565118Z",
    "first_billed_at": "2023-06-22T08:25:12.565118Z",
    "next_billed_at": "2023-09-22T08:25:12.565118Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2023-08-22T08:25:12.565118Z",
      "ends_at": "2023-09-22T08:25:12.565118Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 30,
        "recurring": true,
        "created_at": "2023-06-22T08:25:14.287456Z",
        "updated_at": "2023-08-22T08:32:24.552996Z",
        "previously_billed_at": "2023-08-22T08:25:12.565118Z",
        "next_billed_at": "2023-09-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "description": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3266",
            "currency_code": "USD"
          }
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2023-06-22T08:40:45.808402Z",
        "updated_at": "2023-08-22T08:26:06.361047Z",
        "previously_billed_at": "2023-08-22T08:25:12.565118Z",
        "next_billed_at": "2023-09-22T08:25:12.565118Z",
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "description": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10887",
            "currency_code": "USD"
          }
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h3h3a9sfpr5syq38tq0sd4sp/cancel"
    },
    "discount": null
  },
  "meta": {
    "request_id": "2a8303df-70ce-4c4f-911d-9faf08441a0d"
  }
}
```

{% /api-example %}

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