Apply updates to automatically-collected subscriptions when payment fails

What's new?

We added a new on_payment_failure field that you can include when making changes to subscriptions to tell Paddle how to handle payment failure.

How it works

When making changes to automatically-collected subscriptions where the proration_billing_mode is prorated_immediately or full_immediately, Paddle tries to collect for the amount due right away. Similarly, Paddle collects right away when you bill for one-time charges effective immediately.

Previously, Paddle returned an error if you tried to make a change or bill a one-time charge that resulted in a charge and the payment failed. Your change was not applied.

With this release, you can now optionally include on_payment_failure in your request to tell Paddle how to handle payment failure when updating a subscription or billing for one-time charges.

To apply a change or bill for a one-time charge even if payment fails, set the value to apply_change. The change is applied to the subscription. The subscription remains active, but the related transaction is past_due.

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

Summary of changes

Request bodies

This is a summary of the changes to fields in the Paddle API when working with the update a subscription, preview an update to a subscription, create a one-time charge for a subscription, and preview a one-time charge for a subscription operations:

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.

Learn more