Limits when making subscription changes that result in an immediate charge

What's new?

We've introduced limits when making changes to subscriptions that result in an immediate charge.

There are no changes to endpoints or fields in the API as a result of this change, but there are new errors returned.

How it works

When you update a subscription using prorated_immediately or full_immediately as the proration_billing_mode, Paddle applies the change and attempts to collect payment right away (assuming the charge isn't covered by a credit balance). These are called immediate charges.

To protect the Paddle platform and ensure the best experience for customers, we've introduced hourly and daily limits to the number of immediate charges allowed per subscription. You can make up to 20 chargeable updates to a subscription per hour, with a maximum of 100 per day.

If you exceed the hourly or daily limit for a subscription, Paddle returns a 429 error with information on how to troubleshoot. You can still use prorated_next_billing_period and full_next_billing_period as the proration_billing_mode to bill on the next renewal, or do_not_bill if you don't want to charge for an update.

These limits apply on a per-subscription basis. There's no overall cap on the number of immediate charges you can make across all subscriptions. They're applied across your Paddle account, rather than on a per-IP address or API key basis

This change applies in addition to the existing rate limiting in place across the Paddle API, which remains unchanged.

Next steps

This change is available in version 1 of the Paddle API.

You shouldn't need to make any changes to your implementation.