Just launched
We're actively working on new content and improvements to our documentation. We'd love to hear your thoughts, launch quick survey
Paddle Billing

Change billing dates

Change the billing date of a subscription to change when a customer next pays, and when their subscription renews in the future.

Subscriptions renew automatically when their billing period elapses. For example, a subscription might renew every week, month, or year.

Change the billing date of a subscription when customers want their subscription to renew on a certain day or time every period, like the 1st of the month or the first day of the financial year.

You can't make changes to a subscription if the next billing period is within 30 minutes.

How it works

Paddle automatically creates subscriptions when customers pay for recurring items using the checkout, or when you create and issue invoices using manually-collected transactions.

By default, the billing date for each renewal is based on the date that the subscription was created. For example, if a subscription bills annually then its billing date is every year on the anniversary of when it was created.

Change the billing date against a subscription to change when the subscription renews. This changes the next billing date of the subscription, and the day and time that it renews in the future.

When you change a subscription billing date, you can determine how Paddle should bill for any changes. This is called proration. Paddle's subscription billing engine calculates proration to the minute, allowing for precise billing.

If you choose to prorate:

  • When a customer moves their billing date later than their renewal, Paddle calculates the prorated amount that they owe and bills for it.
  • When a customer moves their billing date sooner than their renewal, Paddle calculates the prorated amount that they already paid for and creates a credit for it.

You can also choose do_not_bill to change the billing date without charging or crediting.

Change billing dates

Send a PATCH request to the /subscriptions/{subscription_id} endpoint.


In the request, include next_billed_at and the proration_billing_mode you'd like to use.


If successful, Paddle returns the updated subscription entity. It includes the next_billed_at date that you set.


transaction.createdOccurs if prorated_immediately is included and Paddle creates a transaction for a prorated amount that a customer owes.
transaction.completedOccurs when payment for a prorated transaction is completed successfully.
subscription.updatedOccurs when the next_billed_at date is changed against a subscription.

Related pages