Update a subscription

patchhttps://api.paddle.com/subscriptions/{subscription_id}

Updates a subscription using its ID.

When making changes to items or the next billing date for a subscription, you must include the proration_billing_mode field to tell Paddle how to bill for those changes.

Send the complete list of items that you'd like to be on a subscription — including existing items. If you omit items, they're removed from the subscription.

For each item, send price_id and quantity. Paddle responds with the full price object for each price. If you're updating an existing item, you can omit the quantity if you don't want to update it.

If successful, your response includes a copy of the updated subscription entity. When an update results in an immediate charge, responses may take longer than usual while a payment attempt is processed.

Path Parameters

subscription_idstringrequired

Paddle ID of the subscription entity to work with.

Request Body

customer_idstring

Paddle ID of the customer that this subscription is for, prefixed with ctm_. Include to change the customer for a subscription.

address_idstring

Paddle ID of the address that this subscription is for, prefixed with add_. Include to change the address for a subscription.

business_idstring or null

Paddle ID of the business that this subscription is for, prefixed with biz_. Include to change the business for a subscription.

currency_codestring

Supported three-letter ISO 4217 currency code. Include to change the currency that a subscription bills in. When changing collection_mode to manual, you may need to change currency code to USD, EUR, or GBP.

next_billed_atstring<date-time>

RFC 3339 datetime string of when this subscription is next scheduled to be billed. Include to change the next billing date.

discountobject or null

Details of the discount applied to this subscription. Include to add a discount to a subscription. null to remove a discount.

idstringrequired

Unique Paddle ID for this discount, prefixed with dsc_.

effective_fromstringrequired

When this discount should take effect from.

collection_modestring

How payment is collected for transactions created for this subscription. automatic for checkout, manual for invoices.

billing_detailsobject or null

Details for invoicing. Required if collection_mode is manual. null if changing collection_mode to automatic.

enable_checkoutboolean

Whether the related transaction may be paid using a Paddle Checkout.

purchase_order_numberstring

Customer purchase order number. Appears on invoice documents.

additional_informationstring or null

Notes or other information to include on this invoice. Appears on invoice documents.

payment_termsobject

How long a customer has to pay this invoice once issued.

intervalstringrequired

Unit of time.

frequencyintegerrequired

Amount of time.

scheduled_changenull

Change that's scheduled to be applied to a subscription. When updating, you may only set to null to remove a scheduled change. Use the pause subscription, cancel subscription, and resume subscription operations to create scheduled changes.

itemsarray[object]

Add a non-catalog price for a non-catalog product in your catalog to a subscription. In this case, the product and price that you're billing for are specific to this subscription.

One of:

Catalog itemNon-catalog price for an existing productNon-catalog price and product

price_idstringrequired

Paddle ID for the price to add to this subscription, prefixed with pri_.

quantitynumber

Quantity of this item to add to the subscription. If updating an existing item and not changing the quantity, you may omit quantity.

custom_dataobject or null

Your own structured key-value data.

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.

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.

Response

dataobject

Represents a subscription entity.

idstring

Unique Paddle ID for this subscription entity, prefixed with sub_.

statusstring

Status of this subscription. Set automatically by Paddle. Use the pause subscription or cancel subscription operations to change.

customer_idstring

Paddle ID of the customer that this subscription is for, prefixed with ctm_.

address_idstring

Paddle ID of the address that this subscription is for, prefixed with add_.

business_idstring or null

Paddle ID of the business that this subscription is for, prefixed with biz_.

currency_codestring

Supported three-letter ISO 4217 currency code. Transactions for this subscription are created in this currency. Must be USD, EUR, or GBP if collection_mode is manual.

created_atstring<date-time>

RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.

updated_atstring<date-time>

RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.

started_atstring<date-time> or null

RFC 3339 datetime string of when this subscription started. This may be different from first_billed_at if the subscription started in trial.

first_billed_atstring<date-time> or null

RFC 3339 datetime string of when this subscription was first billed. This may be different from started_at if the subscription started in trial.

next_billed_atstring<date-time> or null

RFC 3339 datetime string of when this subscription is next scheduled to be billed.

paused_atstring<date-time> or null

RFC 3339 datetime string of when this subscription was paused. Set automatically by Paddle when the pause subscription operation is used. null if not paused.

canceled_atstring<date-time> or null

RFC 3339 datetime string of when this subscription was canceled. Set automatically by Paddle when the cancel subscription operation is used. null if not canceled.

discountobject or null

Details of the discount applied to this subscription.

collection_modestring

How payment is collected for transactions created for this subscription. automatic for checkout, manual for invoices.

billing_detailsobject or null

Details for invoicing. Required if collection_mode is manual.

current_billing_periodobject or null

Current billing period for this subscription. Set automatically by Paddle based on the billing cycle. null for paused and canceled subscriptions.

billing_cycleobject

How often this subscription renews. Set automatically by Paddle based on the prices on this subscription.

scheduled_changeobject or null

Change that's scheduled to be applied to a subscription. Use the pause subscription, cancel subscription, and resume subscription operations to create scheduled changes. null if no scheduled changes.

management_urlsobject

Authenticated customer portal deep links for this subscription. For security, the token appended to each link is temporary. You shouldn't store these links.

itemsarray[object]

Represents a subscription item.

custom_dataobject or null

Your own structured key-value data.

import_metaobject or null

Import information for this entity. null if this entity is not imported.

metaobject

Information about this response.

request_idstring

Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
1{
2  "items": [
3    {
4      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
5      "quantity": 20
6    },
7    {
8      "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
9      "quantity": 1
10    },
11    {
12      "price_id": "pri_01gsz95g2zrkagg294kpstx54r",
13      "quantity": 1
14    }
15  ],
16  "proration_billing_mode": "prorated_immediately"
17}

Response