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.
Before you begin
You can't make changes to a subscription if the next billing period is within 30 minutes, or the subscription status is past_due.
To change the billing date of a subscription, you'll need to get the subscription ID for the subscription you want to change.
You can use the status query parameter when listing with the value active to get a list of active subscriptions.
Change billing dates
- Go to Paddle > Customers, and find the customer whose subscription you want to change.
- Find the subscription under the Subscriptions heading and click it.
- From the subscription overview page, choose Change next billing date
- Enter the new date, then click Save to proceed.
Change billing dates using the API in two steps:
- Preview change Optional
Preview how the proration will apply before committing the change. Present this to customers if you offer an in-app workflow. - Update subscription
Send a request to update the subscription with the new billing date.
Preview change Optional
Send a PATCH request to the /subscriptions/{subscription_id}/preview endpoint to preview the changes you're making to the subscription.
In your request, include next_billed_at (RFC 3339 timestamp) with the new billing date and proration_billing_mode. For billing date changes, only prorated_immediately, prorated_next_billing_period, and do_not_bill are allowed. Optionally include on_payment_failure to control payment failure behavior (defaults to prevent_change).
Previews include immediate_transaction, next_transaction, and recurring_transaction_details. With prorated_next_billing_period, immediate_transaction is null and proration is charged on the next renewal.
{ "next_billed_at": "2024-01-01T00:00:00Z", "proration_billing_mode": "prorated_next_billing_period"}{ "data": { "status": "active", "customer_id": "ctm_01hj3289s46amtzv8vr57xtnxp", "address_id": "add_01hj3289stgx73kjryne7pwzh7", "business_id": null, "currency_code": "USD", "created_at": "2023-12-20T07:33:50.521Z", "updated_at": "2023-12-20T11:36:26.56Z", "started_at": "2023-12-20T07:33:49.542313Z", "first_billed_at": "2023-12-20T07:33:49.542313Z", "next_billed_at": "2024-01-01T00:00:00Z", "paused_at": null, "canceled_at": null, "collection_mode": "automatic", "billing_details": null, "current_billing_period": { "starts_at": "2023-12-20T07:33:49.542313Z", "ends_at": "2024-01-01T00:00:00Z" }, "billing_cycle": { "frequency": 1, "interval": "month" }, "recurring_transaction_details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "40000", "discount": "0", "tax": "3549", "total": "43549" } } ], "totals": { "subtotal": "40000", "tax": "3549", "discount": "0", "total": "43549", "fee": null, "credit": "0", "credit_to_balance": "0", "balance": "43549", "grand_total": "43549", "earnings": null, "currency_code": "USD", "exchange_rate": "1" }, "line_items": [ { "item_id": null, "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 10, "totals": { "subtotal": "30000", "tax": "2662", "discount": "0", "total": "32662" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "ChatApp Pro", "type": "standard", "tax_category": "standard", "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png", "custom_data": { "features": { "crm": true, "data_retention": false, "reports": true }, "suggested_addons": [ "pro_01h1vjes1y163xfj1rh1tkfb65", "pro_01gsz97mq9pa4fkyy0wqenepkz" ], "upgrade_description": "Move from Basic to Pro to take advantage of advanced reporting and a CRM that's right where you're chatting." }, "status": "active", "import_meta": null }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "3000", "discount": "0", "tax": "266", "total": "3266" }, "proration": { "rate": "1", "billing_period": { "starts_at": "2023-12-20T07:33:49.542313Z", "ends_at": "2024-01-01T00:00:00Z" } } }, { "item_id": null, "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1, "totals": { "subtotal": "10000", "tax": "887", "discount": "0", "total": "10887" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Voice rooms addon", "type": "standard", "tax_category": "standard", "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png", "custom_data": null, "status": "active", "import_meta": null }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "10000", "discount": "0", "tax": "887", "total": "10887" }, "proration": { "rate": "1", "billing_period": { "starts_at": "2023-12-20T07:33:49.542313Z", "ends_at": "2024-01-01T00:00:00Z" } } } ] }, "next_transaction": { "billing_period": { "starts_at": "2024-01-01T00:00:00Z", "ends_at": "2024-02-01T00:00:00Z" }, "details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "40000", "discount": "0", "tax": "3549", "total": "43549" } } ], "totals": { "subtotal": "40000", "tax": "3549", "discount": "0", "total": "43549", "fee": null, "credit": "27133", "credit_to_balance": "0", "balance": "16416", "grand_total": "16416", "earnings": null, "currency_code": "USD", "exchange_rate": "1" }, "line_items": [ { "item_id": null, "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 10, "totals": { "subtotal": "30000", "tax": "2662", "discount": "0", "total": "32662" }, "product": { "id": "pro_01gsz4t5hdjse780zja8vvr7jg", "name": "ChatApp Pro", "type": "standard", "tax_category": "standard", "description": "Everything in basic, plus access to a suite of powerful tools and features designed to take your team's productivity to the next level.", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png", "custom_data": { "features": { "crm": true, "data_retention": false, "reports": true }, "suggested_addons": [ "pro_01h1vjes1y163xfj1rh1tkfb65", "pro_01gsz97mq9pa4fkyy0wqenepkz" ], "upgrade_description": "Move from Basic to Pro to take advantage of advanced reporting and a CRM that's right where you're chatting." }, "status": "active", "import_meta": null }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "3000", "discount": "0", "tax": "266", "total": "3266" }, "proration": { "rate": "1", "billing_period": { "starts_at": "2024-01-01T00:00:00Z", "ends_at": "2024-02-01T00:00:00Z" } } }, { "item_id": null, "price_id": "pri_01h1vjfevh5etwq3rb416a23h2", "quantity": 1, "totals": { "subtotal": "10000", "tax": "887", "discount": "0", "total": "10887" }, "product": { "id": "pro_01h1vjes1y163xfj1rh1tkfb65", "name": "Voice rooms addon", "type": "standard", "tax_category": "standard", "description": "Create voice rooms in your chats to work in real time alongside your colleagues. Includes unlimited voice rooms and recording backup for compliance.", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/GcZzBjXRfiraensppgtQ_icon2.png", "custom_data": null, "status": "active", "import_meta": null }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "10000", "discount": "0", "tax": "887", "total": "10887" }, "proration": { "rate": "1", "billing_period": { "starts_at": "2024-01-01T00:00:00Z", "ends_at": "2024-02-01T00:00:00Z" } } } ] }, "adjustments": [ { "transaction_id": "txn_01hj327s2cpxh4mprx55p5qwdz", "items": [ { "item_id": "txnitm_01hj328ac2ak7h82bjfzdk992c", "type": "proration", "amount": "20350", "proration": { "rate": "0.62305", "billing_period": { "starts_at": "2024-01-01T00:00:00Z", "ends_at": "2024-01-20T07:33:49.542313Z" } }, "totals": { "subtotal": "18691", "tax": "1659", "total": "20350" } }, { "item_id": "txnitm_01hj328ac2ak7h82bjg443x4px", "type": "proration", "amount": "6783", "proration": { "rate": "0.62305", "billing_period": { "starts_at": "2024-01-01T00:00:00Z", "ends_at": "2024-01-20T07:33:49.542313Z" } }, "totals": { "subtotal": "6230", "tax": "553", "total": "6783" } } ], "totals": { "subtotal": "24921", "tax": "2212", "total": "27133", "fee": "1378", "earnings": "23543", "currency_code": "USD" } } ] }, "immediate_transaction": null, "scheduled_change": null, "items": [ { "status": "active", "quantity": 10, "recurring": true, "created_at": "2023-12-20T07:33:50.521Z", "updated_at": "2023-12-20T11:36:26.498Z", "previously_billed_at": "2023-12-20T07:33:49.542313Z", "next_billed_at": "2024-01-01T00:00:00Z", "trial_dates": null, "price": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "description": "Monthly (per seat)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "3000", "currency_code": "USD" } } }, { "status": "active", "quantity": 1, "recurring": true, "created_at": "2023-12-20T07:33:50.521Z", "updated_at": "2023-12-20T11:36:26.499Z", "previously_billed_at": "2023-12-20T07:33:49.542313Z", "next_billed_at": "2024-01-01T00:00:00Z", "trial_dates": null, "price": { "id": "pri_01h1vjfevh5etwq3rb416a23h2", "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65", "description": "Monthly (recurring addon)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "10000", "currency_code": "USD" } } } ], "custom_data": null, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01hj32a99syawqhdkkbpxacwgb/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hj32a99syawqhdkkbpxacwgb/cancel" }, "discount": null, "update_summary": { "credit": { "amount": "27133", "currency_code": "USD" }, "charge": { "amount": "0", "currency_code": "USD" }, "result": { "action": "credit", "amount": "27133", "currency_code": "USD" } }, "import_meta": null }, "meta": { "request_id": "905e4427-a654-4591-8ace-432d5450dfe0" }}Update subscription
Send a PATCH request to the /subscriptions/{subscription_id} endpoint to update the subscription.
In your request, include the same body as the preview request.
Paddle updates the subscription.
{ "next_billed_at": "2024-01-01T00:00:00Z", "proration_billing_mode": "prorated_next_billing_period"}{ "data": { "id": "sub_01hj32a99syawqhdkkbpxacwgb", "status": "active", "customer_id": "ctm_01hj3289s46amtzv8vr57xtnxp", "address_id": "add_01hj3289stgx73kjryne7pwzh7", "business_id": null, "currency_code": "USD", "created_at": "2023-12-20T07:33:50.521Z", "updated_at": "2023-12-20T11:42:29.714Z", "started_at": "2023-12-20T07:33:49.542313Z", "first_billed_at": "2023-12-20T07:33:49.542313Z", "next_billed_at": "2024-01-01T00:00:00Z", "paused_at": null, "canceled_at": null, "collection_mode": "automatic", "billing_details": null, "current_billing_period": { "starts_at": "2023-12-20T07:33:49.542313Z", "ends_at": "2024-01-01T00:00:00Z" }, "billing_cycle": { "frequency": 1, "interval": "month" }, "scheduled_change": null, "items": [ { "status": "active", "quantity": 10, "recurring": true, "created_at": "2023-12-20T07:33:50.521Z", "updated_at": "2023-12-20T11:42:29.643Z", "previously_billed_at": "2023-12-20T07:33:49.542313Z", "next_billed_at": "2024-01-01T00:00:00Z", "trial_dates": null, "price": { "id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg", "description": "Monthly (per seat)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "3000", "currency_code": "USD" } } }, { "status": "active", "quantity": 1, "recurring": true, "created_at": "2023-12-20T07:33:50.521Z", "updated_at": "2023-12-20T11:42:29.644Z", "previously_billed_at": "2023-12-20T07:33:49.542313Z", "next_billed_at": "2024-01-01T00:00:00Z", "trial_dates": null, "price": { "id": "pri_01h1vjfevh5etwq3rb416a23h2", "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65", "description": "Monthly (recurring addon)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": null, "unit_price": { "amount": "10000", "currency_code": "USD" } } } ], "custom_data": null, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01hj32a99syawqhdkkbpxacwgb/update-payment-method?token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWhqM2doa3JjOGVlem4yYzFnZndnNHlociIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6Im1hbmFnZW1lbnRfdXJsIiwic2NvcGUiOiJjdXN0b21lci5zdWJzY3JpcHRpb24tcGF5bWVudC51cGRhdGUgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQucmVhZCBjdXN0b21lci5zdWJzY3JpcHRpb24tY2FuY2VsLmNyZWF0ZSBjdXN0b21lci5zdWJzY3JpcHRpb24ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFoajMyODlzNDZhbXR6djh2cjU3eHRueHAiLCJleHAiOjE3MzQ2OTQ5NTAsImlhdCI6MTcwMzA3MjU1MH0.SMb_DeNfwZFzWg-uLhQClUjAVszdDWV7XyJATqpub8Sc6hcaOI1KJRwdhemNu2D5ZiKRRGU3vL7PRZG-pBkbAA", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hj32a99syawqhdkkbpxacwgb/cancel?token=pga_eyJhbGciOiJFZERTQSIsImtpZCI6Imp3a18wMWhkazBuOHF3OG55NTJ5cGNocGNhazA1ayIsInR5cCI6IkpXVCJ9.eyJpZCI6InBnYV8wMWhqM2doa3JjOGVlem4yYzFnZndnNHlociIsInNlbGxlci1pZCI6IjEwODg5IiwidHlwZSI6InN0YW5kYXJkIiwidmVyc2lvbiI6IjEiLCJ1c2FnZSI6Im1hbmFnZW1lbnRfdXJsIiwic2NvcGUiOiJjdXN0b21lci5zdWJzY3JpcHRpb24tcGF5bWVudC51cGRhdGUgY3VzdG9tZXIuc3Vic2NyaXB0aW9uLXBheW1lbnQucmVhZCBjdXN0b21lci5zdWJzY3JpcHRpb24tY2FuY2VsLmNyZWF0ZSBjdXN0b21lci5zdWJzY3JpcHRpb24ucmVhZCIsImlzcyI6Imd1ZXN0YWNjZXNzLXNlcnZpY2UiLCJzdWIiOiJjdG1fMDFoajMyODlzNDZhbXR6djh2cjU3eHRueHAiLCJleHAiOjE3MzQ2OTQ5NTAsImlhdCI6MTcwMzA3MjU1MH0.SMb_DeNfwZFzWg-uLhQClUjAVszdDWV7XyJATqpub8Sc6hcaOI1KJRwdhemNu2D5ZiKRRGU3vL7PRZG-pBkbAA" }, "discount": null, "import_meta": null }, "meta": { "request_id": "87ac24c4-a4b4-42b2-a13a-903d0cf06b9d" }}Events
transaction.created | Occurs when a transaction is created. |
transaction.completed | Occurs when a transaction is completed. Its status field changes to completed. |
subscription.updated | Occurs when a subscription is updated. |