Update trialing subscriptions
Add or remove recurring items, change quantities, bill for one-time charges, and change the next billing date for subscriptions in trial.
What's new?
You can now update trialing subscriptions, including:
- Adding or removing items
- Changing quantities
- Billing for one-time charges
- Changing the next billing date
There are no changes to endpoints or fields in the API as a result of this change — it's an update to the way the Paddle platform handles trialing subscriptions.
How it works
Previously, you couldn't make changes to a trialing subscription. We updated the Paddle platform so now you can add or remove items, change quantities, bill for one-time charges, and change the next billing date. This lets you do things like:
- Extend or cut short a trial by changing the next billing date
- Bill for charges or fees, like importing or setup
You might let customers make changes to their subscription as part of a workflow where they confirm and activate their subscription, transitioning to a paid plan.
Proration doesn't apply to updates made to a subscription that's in trial. You must use
do_not_billas theproration_billing_modewhen sending requests.
Here's a list of the fields you can update where a subscription status is trialing:
Represents a subscription entity.
List of items on this subscription. Only recurring items may be added. Send the complete list of items that should be on this subscription, including existing items to retain.
RFC 3339 datetime string of when this subscription is next scheduled to be billed. Include to change the next billing date.
Changes to error messages
This change is an update to the way the Paddle platform handles trialing subscriptions. Error messages are the same, but may be returned in different circumstances:
- The
subscription_update_when_trialingerror message is no longer returned when adding or removing items, changing item quantities, billing for one-time charges, or changing the next billing date for trialing subscriptions. It's still returned when making other changes to trialing subscriptions. - The
subscription_trialing_items_update_invalid_optionserror message is returned when adding or removing items from a trialing subscription when theproration_billing_modeis a value other thando_not_bill.
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.
Check out our work with trials guide to get started.
