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 first of the month or the first day of the financial year.

Working with trialing subscriptions? You can extend a trial or cut a trial short to bill for it right away, see Extend or activate a trial

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 its creation.

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.

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

Change billing dates

API

Dashboard

Change the next billing date for a subscription using the API in three steps:

Build a request
Create a request that includes your new next billing date as the next_billed_at date, along with a proration_billing_mode to say how Paddle should handle proration.
Preview your changes
Preview the impact that changing the billing date has on the regular amount the customer pays and the next renewal, as well as any immediate charges. This is optional, but recommended — you should present charge information to the customer.
Update the subscription
Send the request to apply the changes. Paddle updates the subscription.

Build request

Build a request that includes next_billed_at with the date and time the subscription should next bill.

next_billed_atstring<date-time>

RFC 3339 datetime string of when this subscription is next scheduled to be billed. Include to change the next billing date.

Along with the next_billed_at field, you must include the proration_billing_mode field to tell Paddle how to bill for the changed date.

You can only use prorated_immediately, prorated_next_billing_period, and do_not_bill when changing billing dates for a subscription.

proration_billing_modestring

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.

When changing billing dates for automatically-collected subscriptions where the proration_billing_mode is prorated_immediately, Paddle tries to collect for the amount due right away.

You can optionally include on_payment_failure to tell Paddle how to handle failed payment when updating a subscription.

If omitted, this defaults to prevent_change meaning that Paddle returns an error and doesn't apply subscription changes when payment fails.

on_payment_failurestring

How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to prevent_change.

Request

This example changes the billing date for a subscription to January 1, 2024.

1
2
3
4
1{
2  "next_billed_at": "2024-01-01T00:00:00Z",
3  "proration_billing_mode": "prorated_next_billing_period"
4}

Preview changes

Send a PATCH request to the /subscriptions/{subscription_id}/preview endpoint with the request you built.

PATCHhttps://api.paddle.com/subscriptions/{subscription_id}/preview

subscription_idstring

Paddle ID of the subscription entity to work with.

Response

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

Previews include immediate_transaction, next_transaction, and recurring_transaction_details that give you information about upcoming transactions impacted as a result of this change. In this example, proration_billing_mode is prorated_next_billing, meaning:

Paddle doesn't create a charge immediately, so immediate_transaction is null
Paddle calculates proration and charges for them on the next renewal, detailed in next_transaction

200 OK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "status": "active",
4    "customer_id": "ctm_01hj3289s46amtzv8vr57xtnxp",
5    "address_id": "add_01hj3289stgx73kjryne7pwzh7",
6    "business_id": null,
7    "currency_code": "USD",
8    "created_at": "2023-12-20T07:33:50.521Z",
9    "updated_at": "2023-12-20T11:36:26.56Z",
10    "started_at": "2023-12-20T07:33:49.542313Z",
11    "first_billed_at": "2023-12-20T07:33:49.542313Z",
12    "next_billed_at": "2024-01-01T00:00:00Z",
13    "paused_at": null,
14    "canceled_at": null,
15    "collection_mode": "automatic",
16    "billing_details": null,
17    "current_billing_period": {
18      "starts_at": "2023-12-20T07:33:49.542313Z",
19      "ends_at": "2024-01-01T00:00:00Z"
20    },

Update subscription

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

PATCHhttps://api.paddle.com/subscriptions/{subscription_id}

subscription_idstring

Paddle ID of the subscription entity to work with.

Response

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

200 OK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "sub_01hj32a99syawqhdkkbpxacwgb",
4    "status": "active",
5    "customer_id": "ctm_01hj3289s46amtzv8vr57xtnxp",
6    "address_id": "add_01hj3289stgx73kjryne7pwzh7",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2023-12-20T07:33:50.521Z",
10    "updated_at": "2023-12-20T11:42:29.714Z",
11    "started_at": "2023-12-20T07:33:49.542313Z",
12    "first_billed_at": "2023-12-20T07:33:49.542313Z",
13    "next_billed_at": "2024-01-01T00: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-12-20T07:33:49.542313Z",
20      "ends_at": "2024-01-01T00:00:00Z"

Events

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

Subscription entity overview

Proration