Skip to main content
PATCH
/
subscriptions
/
{subscription_id}
Update a subscription
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {price_id: 'pri_01gsz8x8sawmvhz1pv30nge1ke', quantity: 20},
      {price_id: 'pri_01h1vjfevh5etwq3rb416a23h2', quantity: 1},
      {price_id: 'pri_01gsz95g2zrkagg294kpstx54r', quantity: 1}
    ],
    proration_billing_mode: 'prorated_immediately'
  })
};

fetch('https://api.paddle.com/subscriptions/{subscription_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "data": {
    "id": "sub_01hv8y5ehszzq0yv20ttx3166y",
    "status": "active",
    "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j",
    "address_id": "add_01hv8y4jk511j9g2n9a2mexjbx",
    "business_id": null,
    "currency_code": "USD",
    "created_at": "2024-04-12T10:38:00.761Z",
    "updated_at": "2024-04-12T10:49:38.771Z",
    "started_at": "2024-04-12T10:37:59.556997Z",
    "first_billed_at": "2024-04-12T10:37:59.556997Z",
    "next_billed_at": "2024-05-12T10:37:59.556997Z",
    "paused_at": null,
    "canceled_at": null,
    "collection_mode": "automatic",
    "billing_details": null,
    "current_billing_period": {
      "starts_at": "2024-04-12T10:37:59.556997Z",
      "ends_at": "2024-05-12T10:37:59.556997Z"
    },
    "billing_cycle": {
      "frequency": 1,
      "interval": "month"
    },
    "scheduled_change": null,
    "items": [
      {
        "status": "active",
        "quantity": 20,
        "recurring": true,
        "created_at": "2024-04-12T10:38:00.761Z",
        "updated_at": "2024-04-12T10:49:38.76Z",
        "previously_billed_at": "2024-04-12T10:37:59.556997Z",
        "next_billed_at": "2024-05-12T10:37:59.556997Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (per seat)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "3000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 999
          },
          "import_meta": null,
          "created_at": "2023-02-23T13:55:22.538367Z",
          "updated_at": "2024-04-11T13:54:52.254748Z"
        },
        "product": {
          "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "name": "AeroEdit Pro",
          "type": "standard",
          "tax_category": "standard",
          "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png",
          "custom_data": {
            "features": {
              "aircraft_performance": true,
              "compliance_monitoring": true,
              "flight_log_management": true,
              "payment_by_invoice": false,
              "route_planning": true,
              "sso": false
            },
            "suggested_addons": [
              "pro_01h1vjes1y163xfj1rh1tkfb65",
              "pro_01gsz97mq9pa4fkyy0wqenepkz"
            ],
            "upgrade_description": "Move from Basic to Pro to take advantage of aircraft performance, advanced route planning, and compliance monitoring."
          },
          "status": "active",
          "import_meta": null,
          "created_at": "2023-02-23T12:43:46.605Z",
          "updated_at": "2024-04-05T15:53:44.687Z"
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2024-04-12T10:38:00.761Z",
        "updated_at": "2024-04-12T10:38:00.761Z",
        "previously_billed_at": "2024-04-12T10:37:59.556997Z",
        "next_billed_at": "2024-05-12T10:37:59.556997Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "type": "standard",
          "description": "Monthly",
          "name": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "10000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "import_meta": null,
          "created_at": "2023-06-01T13:31:12.625056Z",
          "updated_at": "2024-04-09T07:23:00.907834Z"
        },
        "product": {
          "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "name": "Analytics addon",
          "type": "standard",
          "tax_category": "standard",
          "description": "Unlock advanced insights into your flight data with enhanced analytics and reporting features. Includes customizable reporting templates and trend analysis across flights.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png",
          "custom_data": null,
          "status": "active",
          "import_meta": null,
          "created_at": "2023-06-01T13:30:50.302Z",
          "updated_at": "2024-04-05T15:47:17.163Z"
        }
      },
      {
        "status": "active",
        "quantity": 1,
        "recurring": true,
        "created_at": "2024-04-12T10:49:38.765Z",
        "updated_at": "2024-04-12T10:49:38.765Z",
        "previously_billed_at": "2024-04-12T10:49:38.765Z",
        "next_billed_at": "2024-05-12T10:37:59.556997Z",
        "trial_dates": null,
        "price": {
          "id": "pri_01gsz95g2zrkagg294kpstx54r",
          "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "type": "standard",
          "description": "Monthly (recurring addon)",
          "name": "Monthly (recurring addon)",
          "tax_mode": "account_setting",
          "billing_cycle": {
            "frequency": 1,
            "interval": "month"
          },
          "trial_period": null,
          "unit_price": {
            "amount": "25000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "import_meta": null,
          "created_at": "2023-02-23T13:59:52.159927Z",
          "updated_at": "2024-04-09T07:27:48.018296Z"
        },
        "product": {
          "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz",
          "name": "VIP support",
          "type": "standard",
          "tax_category": "standard",
          "description": "Get exclusive access to our expert team of product specialists, available to help you make the most of your AeroEdit subscription.",
          "image_url": "https://paddle.s3.amazonaws.com/user/165798/qgyipKJwRtq98YNboipo_vip-support.png",
          "custom_data": null,
          "status": "active",
          "import_meta": null,
          "created_at": "2023-02-23T13:58:17.615Z",
          "updated_at": "2024-04-05T15:44:02.893Z"
        }
      }
    ],
    "custom_data": null,
    "management_urls": {
      "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01hv8y5ehszzq0yv20ttx3166y/update-payment-method",
      "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hv8y5ehszzq0yv20ttx3166y/cancel"
    },
    "discount": null,
    "import_meta": null
  },
  "meta": {
    "request_id": "fd763d79-df30-41dd-9c59-adde4cf02cd3"
  }
}

Authorizations

​
Authorization
string
header
required

Requests are authenticated with API keys. Provide your API key as a Bearer token in the Authorization header.

API keys are assigned permissions, granting them access to entities and operations. Each endpoint may require one or more permissions, defined with the x-permissions extension. Values for include parameters may require specific permissions as defined in the x-enum-permissions extension. See all available permissions in the permission schema or documentation.

Get an API key and select the permissions you need from the Paddle dashboard under Paddle > Developer Tools > Authentication.

Path Parameters

​
subscription_id
string
required

Paddle ID of the subscription entity to work with.

Example:

"sub_01gvne45dvdhg5gdxrz6hh511r"

Body

application/json

Represents a subscription entity when updating subscriptions.

​
customer_id
string

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

Example:

"ctm_01grnn4zta5a1mf02jjze7y2ys"

​
address_id
string

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

Example:

"add_01gm302t81w94gyjpjpqypkzkf"

​
business_id
string | null

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

Example:

"biz_01grrebrzaee2qj2fqqhmcyzaj"

​
currency_code
enum<string>

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.

Available options:
USD,
EUR,
GBP,
JPY,
AUD,
CAD,
CHF,
HKD,
SGD,
SEK,
ARS,
BRL,
CNY,
COP,
CZK,
DKK,
HUF,
ILS,
INR,
KRW,
MXN,
NOK,
NZD,
PLN,
RUB,
THB,
TRY,
TWD,
UAH,
VND,
ZAR
Required string length: 3
​
next_billed_at
string<date-time>

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

Example:

"2024-10-12T07:20:50.52Z"

​
discount
SubscriptionDiscountEffectiveFrom · object

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

​
collection_mode
enum<string>
default:automatic

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

Available options:
automatic,
manual
​
billing_details
Billing details (update) · object

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

​
scheduled_change
null

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.

​
items
(Catalog item · object | Non-catalog price for an existing product · object | Non-catalog price and product · 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 to retain.

Required array length: 1 - 100 elements

Add or update a catalog item to a subscription. In this case, the product and price that you're billing for exist in your product catalog in Paddle.

​
custom_data
Custom data · object

Your own structured key-value data.

Example:
{ "customer_reference_id": "abcd1234" }
​
proration_billing_mode
enum<string>

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.

Available options:
prorated_immediately,
prorated_next_billing_period,
full_immediately,
full_next_billing_period,
do_not_bill
​
on_payment_failure
enum<string>
default:prevent_change

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

Available options:
prevent_change,
apply_change

Response

OK

​
data
Subscription · object
required

Represents a subscription entity.

​
meta
Meta · object
required

Information about this response.