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.
Paddle ID of the subscription entity to work with.
Request
In the request, include next_billed_at
and the proration_billing_mode
you'd like to use.
12341{
2 "next_billed_at": "2024-05-15T00:00:00Z",
3 "proration_billing_mode": "prorated_immediately"
4}
Response
If successful, Paddle returns the updated subscription entity. It includes the next_billed_at
date that you set.
12345678910111213141516171819201{
2 "data": {
3 "id": "sub_01gyfarwx0584bj7cyc3fxxry0",
4 "status": "active",
5 "customer_id": "ctm_01gyfaqdgdb0fqctkfv8c56fxk",
6 "address_id": "add_01gyfaqdjp3gcr9pv2k1agrd44",
7 "business_id": null,
8 "currency_code": "USD",
9 "created_at": "2023-04-20T12:38:34.656936Z",
10 "updated_at": "2023-04-20T15:26:03.043416Z",
11 "started_at": "2023-04-20T12:38:32.75251Z",
12 "first_billed_at": "2023-04-20T12:38:32.75251Z",
13 "next_billed_at": "2024-05-15T00:00:00Z",
14 "paused_at": null,
15 "canceled_at": null,
16 "collection_mode": "automatic",
17 "billing_details": null,
18 "current_billing_period": {
19 "starts_at": "2023-04-20T12:38:32.75251Z",
20 "ends_at": "2024-05-15T00:00:00Z"
Notifications
transaction.created | Occurs if prorated_immediately is included and Paddle creates a transaction for a prorated amount that a customer owes. |
transaction.completed | Occurs when payment for a prorated transaction is completed successfully. |
subscription.updated | Occurs when the next_billed_at date is changed against a subscription. |