PApaddlehq
Subscriptions

Update a subscription

Changed on

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.

You can't update a subscription that's past_due, except to remove a scheduled change by setting scheduled_change to null.

patch/subscriptions/{subscription_id}

Request

  • Base URL
    https://sandbox-api.paddle.com
  • Auth
    HTTP bearer

Path parameters

subscription_idstring required

Paddle ID of the subscription entity to work with.

Request body

customer_idstring

Unique Paddle ID for this customer entity, prefixed with ctm_.

address_idstring

Unique Paddle ID for this address entity, prefixed with add_.

business_idstring

Unique Paddle ID for this business entity, prefixed with biz_.

currency_code'USD' | 'EUR' | 'GBP' | 'JPY' | 'AUD' | 'CAD' | 'CHF' | 'HKD' | 'SGD' | 'SEK' | 'ARS' | 'BRL' | 'CLP' | 'CNY' | 'COP' | 'CZK' | 'DKK' | 'HUF' | 'ILS' | 'INR' | 'KRW' | 'MXN' | 'NOK' | 'NZD' | 'PEN' | 'PLN' | 'RUB' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'VND' | 'ZAR'

Supported three-letter ISO 4217 currency code.

next_billed_atstring date-time

RFC 3339 datetime string.

collection_mode'automatic' | 'manual'

How payment is collected. automatic for checkout, manual for invoices.

scheduled_changeunknown
custom_dataCustomData

Your own structured key-value data.

proration_billing_mode'prorated_immediately' | 'prorated_next_billing_period' | 'full_immediately' | 'full_next_billing_period' | 'do_not_bill'

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_failure'prevent_change' | 'apply_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.

Example request

{
  "customer_id": "ctm_01grnn4zta5a1mf02jjze7y2ys",
  "address_id": "add_01gm302t81w94gyjpjpqypkzkf",
  "business_id": "biz_01grrebrzaee2qj2fqqhmcyzaj",
  "next_billed_at": "2024-10-12T07:20:50.52Z",
  "discount": {
    "id": "dsc_01gv5kpg05xp104ek2fmgjwttf"
  },
  "items": [
    {
      "price_id": "pri_01gsz8z1q1n00f12qt82y31smh"
    }
  ],
  "custom_data": {
    "customer_reference_id": "abcd1234"
  }
}

Response

The request has succeeded.

Changes

  • v14f35a8c6ea4dRevision changes
    • breaking

      removed from the ///// request property anyOf list

    • breaking

      removed from the ///// request property anyOf list

    • breaking

      added to the ////////// response property oneOf list for the response status

    • breaking

      added to the //////// response property oneOf list for the response status

    • info

      added to the ///// request property anyOf list

    • info

      added to the ///// request property anyOf list

    • info

      added to the //////// request property oneOf list

    • info

      added to the //////// request property oneOf list

    • info

      added the required property /// to the response with the status

  • v1e1ac347eb3c5Revision changes
    • warning

      added the new CLP enum value to the // response property for the response status

    • warning

      added the new CLP enum value to the /////// response property for the response status

    • warning

      added the new CLP enum value to the ///////// response property for the response status

    • warning

      added the new PEN enum value to the // response property for the response status

    • warning

      added the new PEN enum value to the /////// response property for the response status

    • warning

      added the new PEN enum value to the ///////// response property for the response status

    • info

      added the new CLP enum value to the request property /

    • info

      added the new CLP enum value to the request property ///////

    • info

      added the new CLP enum value to the request property /////////

    • info

      added the new CLP enum value to the request property ///////

    • info

      added the new CLP enum value to the request property /////////

    • info

      added the new PEN enum value to the request property /

    • info

      added the new PEN enum value to the request property ///////

    • info

      added the new PEN enum value to the request property /////////

    • info

      added the new PEN enum value to the request property ///////

    • info

      added the new PEN enum value to the request property /////////

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added to the / response property anyOf list for the response status

    • info

      removed from the / response property anyOf list for the response status

    • info

      added the required property / to the response with the status