Control how Paddle bills for subscriptions when resuming
Choose whether Paddle should start a new billing period or continue the existing one when resuming a paused subscription.
What's new?
We've added a new on_resume field that you can include when making a request to pause or resume a subscription to tell Paddle how to handle charging.
How Paddle should set the billing period for the subscription when resuming. If omitted, defaults to start_new_billing_period.
How it works
Previously, when pausing a subscription midway through a billing period, the billing period against the subscription was set to null. This means when you resume a subscription, Paddle started a new billing period and immediately charged for the period ahead.
With this release, Paddle retains the billing period against the subscription when you pause, and there's a new on_resume option that you can use to determine how Paddle charges for a subscription when resuming.
To continue the existing billing period, set the value to continue_existing_billing_period. If the customer resumes before the end date of the existing billing period, there's no immediate charge.
If omitted, this defaults to start_new_billing_period. The billing period is reset to the date and time that the subscription was resumed, and Paddle immediately charges the full amount for the new billing period.
Summary of changes
This is a summary of the changes to fields in the Paddle API:
| Field | Change | Notes |
|---|---|---|
on_resume | New field | Include in request bodies when pausing or resuming subscriptions. |
subscription.current_biling_period | Behavior change | Now returns an object when subscription.status is paused. Previously null. |
Next steps
This change is available in version 1 of the Paddle API.
It's a non-breaking change, meaning it doesn't impact existing integrations. The default behavior is unchanged.
