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.
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.
Summary of changes
| Entity | Field | Change | Type |
|---|---|---|---|
| Subscription | on_resume | + Added | Field |
| Include in request bodies when pausing or resuming subscriptions. | |||
| Subscription | subscription.current_biling_period | ~ Updated | Field |
| Now returns an object when subscription.status is paused. Previously null. | |||
| Errors | subscription_continuing_existing_billing_period_not_allowed | + Added | Field |
| Errors | subscription_continuing_existing_billing_period_not_allowed_subscription_past_due | + Added | Field |