PApaddlehq
Subscriptions

Create a one-time charge for a subscription

Changed on

Creates a new one-time charge for a subscription. Use to bill non-recurring items to a subscription. Non-recurring items are price entities where the billing_cycle is null.

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

If successful, Paddle responds with the updated subscription entity. However, one-time charges aren't held against the subscription entity, so the charges billed aren't returned in the response.

Once created, to get details of a one-time charge:

  • When created with effective_from as next_billing_period, get the subscription the charge was billed to and use the include query parameter with the next_transaction value.
  • When created with effective_from as immediately, list transactions and use the subscription_id query parameter with the subscription ID of the subscription the charge was billed to.

When an update results in an immediate charge, responses may take longer than usual while a payment attempt is processed.

post/subscriptions/{subscription_id}/charge

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 and a new resource has been created as a result.

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 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