Paddle Billing
Search

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

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.

Proration

When you make changes to items, you can determine how Paddle should bill for those changes. This is called proration. 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

    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

    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

You can't make changes to a subscription if the next billing period is within 30 minutes, or the subscription status is past_due.

Get subscription and extract existing prices

If you're working with the API, you'll need to get and extract existing items on a subscription first.

This is because when updating subscription items, Paddle expects the complete list of items that you'd like to be on the subscription — including existing items. If you don't include an existing item, it's removed from the subscription.

See: Work with lists

Send a GET request to the /subscriptions/{subscription_id} endpoint.

Response

Paddle returns the complete subscription entity for the ID you specified.

Extract the price ID from the price object and the quantity for each item in the items array. Keep those for the next step.

Add items to a subscription

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

You can only add recurring items. Recurring items are prices that have a billing_cycle set against them.

You can use any proration billing mode.

Recurring items on a subscription must have the same billing interval. For example, you can't have a subscription with some products that are billed monthly and some products that are billed annually.

Add recurring items to a subscription using the API in three steps:

  1. Build a request

    Create an items list that includes existing items and new items, then choose your proration mode.

  2. Preview your changes

    Preview the impact of the new items on the regular amount the customer pays and the next renewal, as well as any immediate charges. This is optional, but recommended — you should present charge information to a customer.

  3. Update the subscription

    Send the request to apply the changes you previewed. Paddle updates the subscription.

Build request

Build a request that includes an items array. Your array should include an object for each item, where each object contains a price ID and a quantity.

Include existing price IDs that you extracted in the previous step, as well as any new items that you'd like to add.

You may omit quantity for existing items where you're not making changes to the quantity.

itemsarray[object]

List of items on this subscription. Only recurring items may be added. Send the complete list of items that should be on this subscription, including existing items that you'd like to keep.

quantityinteger

Quantity to bill for.

price_idstring

Paddle ID of an an existing catalog price to bill for.

Along with your items array, you must include the proration_billing_mode field to tell Paddle how to bill for the added items.

proration_billing_modestring

How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing.

For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used.

When making changes to automatically-collected subscriptions where the proration_billing_mode is prorated_immediately or full_immediately, Paddle tries to collect for the amount due right away.

You can optionally include on_payment_failure to tell Paddle how to handle payment failure when updating a subscription.

If omitted, this defaults to prevent_change meaning that Paddle returns an error and doesn't apply subscription changes when payment fails.

on_payment_failurestring

How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to prevent_change.

Request

This example adds two new items with a quantity of 1 each. There's no quantity for the final item because it already exists on the subscription. Its quantity won't be changed.

It includes prorated_immediately as the billing mode, meaning Paddle calculates a prorated charge for the new items and bills for it on the next renewal.

Preview change

Send a PATCH request to the /subscriptions/{subscription_id}/preview endpoint with the request you built.

Response

If successful, Paddle returns a preview of the updated subscription entity.

The items list contains complete objects for items on the subscription, including billing information and information about the related price.

Previews include immediate_transaction, next_transaction, and recurring_transaction_details that give you information about upcoming transactions impacted as a result of this change. In this example, proration_billing_mode is prorated_next_billing, meaning:

  • Paddle doesn't create a charge immediately, so immediate_transaction is null
  • Paddle calculates proration and charges for them on the next renewal, detailed in next_transaction

Update subscription

Send a PATCH request to the /subscriptions/{subscription_id} endpoint with the request you built.

Response

If successful, Paddle returns a copy of the updated subscription entity.

The items list contains complete objects for items on the subscription, including billing information and information about the related price.

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

Remove recurring items from a subscription using the API in three steps:

  1. Build a request

    Create an items list that has the list of items that you'd like to keep on the subscription, then choose your proration mode.

  2. Preview your changes

    Preview the impact of removing the items on the regular amount the customer pays and the next renewal. This is optional, but recommended — you should present charge information to a customer.

  3. Update the subscription

    Send the request to apply the changes you previewed. Paddle updates the subscription.

Build request

Build an array of items, with an object containing either:

  • An item from your catalog

    Include a price ID and quantity for each item.

  • A non-catalog item

    Include a price object and quantity for each item.

Non-catalog items are one-off or bespoke items that are specific to that transaction. See: Bill for non-catalog items

To remove items, don't include them in the array.

You may omit quantity for existing items where you're not making changes to the quantity.

Subscriptions must have at least one item. Consider canceling a subscription entirely, or pausing to stop billing temporarily.

itemsarray[object]

List of items on this subscription. Only recurring items may be added. Send the complete list of items that should be on this subscription, including existing items that you'd like to keep.

quantityinteger

Quantity to bill for.

price_idstring

Paddle ID of an an existing catalog price to bill for.

Along with your items array, you must include the proration_billing_mode field to tell Paddle how to bill for the removed items.

proration_billing_modestring

How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing.

For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used.

When making changes to automatically-collected subscriptions where the proration_billing_mode is prorated_immediately or full_immediately, Paddle tries to collect for the amount due right away.

You can optionally include on_payment_failure to tell Paddle how to handle payment failure when updating a subscription.

If omitted, this defaults to prevent_change meaning that Paddle returns an error and doesn't apply subscription changes when payment fails.

on_payment_failurestring

How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to prevent_change.

Request

This example includes two items with a quantity of 1 each. There's no quantity for either item because they already exist on the subscription. Their quantities won't be changed.

It includes prorated_next_billing as the billing mode, meaning Paddle calculates a prorated credit for the removed items and applies it to the next transaction.

Preview change

Send a PATCH request to the /subscriptions/{subscription_id}/preview endpoint with the request you built.

Response

If successful, Paddle returns a preview of the updated subscription entity.

The items list contains complete objects for items on the subscription, including billing information and information about the related price.

Previews include immediate_transaction, next_transaction, and recurring_transaction_details that give you information about upcoming transactions impacted as a result of this change. In this example, proration_billing_mode is prorated_next_billing, meaning:

  • Paddle doesn't create a charge immediately, so immediate_transaction is null
  • Paddle calculates proration and charges for them on the next renewal, detailed in next_transaction

As an item was removed, Paddle calculates a credit and deducts this from the next renewal.

Update subscription

Send a PATCH request to the /subscriptions/{subscription_id} endpoint with the request you built.

Response

If successful, Paddle returns a copy of the updated subscription entity.

The items list contains complete objects for items on the subscription, including billing information and information about the related price.

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 you bill per user or seat. They might call it "upgrading" when increasing units, and "downgrading" when decreasing units.

You can choose any proration billing mode.

Change quantities for recurring items on a subscription using the API in three steps:

  1. Build a request

    Create an items list that includes the items and their new quantities, then choose your proration mode.

  2. Preview your changes

    Preview the impact of the changed quantities on the regular amount the customer pays and the next renewal, as well as any immediate charges. This is optional, but recommended — you should present charge information to a customer.

  3. Update the subscription

    Send the request to apply the changes you previewed. Paddle updates the subscription.

Build request

Build an array of items, with an object containing either:

  • An item from your catalog

    Include a price ID and quantity for each item.

  • A non-catalog item

    Include a price object and quantity for each item.

Non-catalog items are one-off or bespoke items that are specific to that transaction. See: Bill for non-catalog items

If you're just changing quantities, your items array should include the same price IDs with different quantities.

You may omit quantity for existing items where you're not making changes to the quantity.

itemsarray[object]

List of items on this subscription. Only recurring items may be added. Send the complete list of items that should be on this subscription, including existing items that you'd like to keep.

quantityinteger

Quantity to bill for.

price_idstring

Paddle ID of an an existing catalog price to bill for.

Along with your items array, you must include the proration_billing_mode field to tell Paddle how to bill for the quantity changes.

proration_billing_modestring

How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing.

For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used.

When making changes to automatically-collected subscriptions where the proration_billing_mode is prorated_immediately or full_immediately, Paddle tries to collect for the amount due right away.

You can optionally include on_payment_failure to tell Paddle how to handle payment failure when updating a subscription.

If omitted, this defaults to prevent_change meaning that Paddle returns an error and doesn't apply subscription changes when payment fails.

on_payment_failurestring

How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to prevent_change.

Request

This example includes two items. There's no quantity for the first item, which already exists on the subscription. Its quantity won't be changed. The quantity for the second item has been increased to 30 from 10.

It includes prorated_immediately as the billing mode, meaning Paddle calculates a prorated charge for the additional units and bills for it on the next renewal.

Preview change

Send a PATCH request to the /subscriptions/{subscription_id}/preview endpoint with the request you built.

Response

If successful, Paddle returns a preview of the updated subscription entity.

The items list contains complete objects for items on the subscription, including billing information and information about the related price.

Previews include immediate_transaction, next_transaction, and recurring_transaction_details that give you information about upcoming transactions impacted as a result of this change. In this example, proration_billing_mode is prorated_immedidately, meaning Paddle calculates proration and charges immediately, detailed immediate_transaction.

Update subscription

Send a PATCH request to the /subscriptions/{subscription_id} endpoint with the request you built.

Response

If successful, Paddle returns a copy of the updated subscription entity.

The items list contains complete objects for items on the subscription, including billing information and information about the related price.

Events

subscription.updatedOccurs when you update items on a subscription.
adjustment.createdOccurs when you choose a proration billing mode that prorates and bills for changes immediately.
transaction.createdOccurs when you choose a proration billing mode that bills the customer for changes immediately.

Related pages