Account2

Addresses4

Adjustments3

API root1

Businesses4

Checkout domains4

Client tokens4

Countries1

Currencies1

Customer portals1

Customers6

Discount groups4

Discounts4

Event types1

Events1

IP addresses1

Metrics9

Notification logs1

Notification settings5

Notifications3

Payment methods3

Prices4

Pricing preview1

Products4

Reports4

Settings18

Simulation run events3

Simulation runs3

Simulation types1

Simulations4

Subscription history1

Subscriptions11

Transactions7

Verifications2

Webhooks

Addresses3

Adjustments2

API keys6

Businesses3

Client tokens3

Customers3

Discount groups2

Discounts3

Payment methods2

Payouts2

Prices3

Products3

Reports2

Subscriptions9

Transactions10

Subscriptions

Preview an update to a subscription

Changed on Oct 19, 2026

Previews an update for a subscription without applying those changes. Typically used for previewing proration before making changes to a subscription.

If successful, your response includes immediate_transaction, next_transaction, and recurring_transaction_details so you can see expected transactions for the changes.

The update_summary object contains details of prorated credits and charges created, along with the overall result of the update.

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

patch/subscriptions/{subscription_id}/preview

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

Oct 19, 2026v14f35a8c6ea4d Revision 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
Jul 9, 2026v1e1ac347eb3c5 Revision 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 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 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 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
- 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
- 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
- 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

Operation history (13 revisions)