Limits when making subscription changes that result in an immediate charge
We've introduced hourly and daily limits to the number of immediate charges you can make per subscription. You can make up to 20 chargeable updates to a subscription per hour, with a maximum of 100 per day.
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.
Summary of changes
Changes to error messages
This change is an update to the way the Paddle platform handles subscription updates that result in an immediate charge. There are two new error messages:
subscription_immediate_charge_hour_limit_exceeded | Returned when you make too many charges to a subscription in an hour. |
subscription_immediate_charge_24_hour_limit_exceeded | Returned when you make too many charges to a subscription in a day. |
Next steps
This change is available in version 1 of the Paddle API.
You shouldn't need to make any changes to your implementation.
