PApaddlehq
Subscriptions

Preview a one-time charge for a subscription

Changed on

Previews creating a one-time charge for a subscription without billing that charge. Typically used for previewing calculations before making changes to a subscription.

One-time charges are non-recurring items. These are price entities where the billing_cycle is null.

You can't preview one-time charges for subscriptions that are past_due.

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

post/subscriptions/{subscription_id}/charge/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

effective_from'next_billing_period' | 'immediately' required

When this subscription change should take effect from. Defaults to next_billing_period, which creates a scheduled_change to apply the subscription change at the end of the billing period.

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

{
  "items": [
    {
      "quantity": 5,
      "price_id": "pri_01gsz8z1q1n00f12qt82y31smh"
    }
  ]
}

Response

The request has succeeded.

Changes

  • v14f35a8c6ea4dRevision changes
    • 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 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 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 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