Update trialing subscriptions

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:

Upgrade or downgrade a plan
Add or remove addons or additional modules
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_bill as the proration_billing_mode when sending requests.

Here's a list of the fields you can update where a subscription status is trialing:

subscription object

Represents a subscription entity.

items array

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.

next_billed_at string

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_trialing error 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_options error message is returned when adding or removing items from a trialing subscription when the proration_billing_mode is a value other than do_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.

Entity	Field	Change	Type
Subscriptions	`subscription_trialing_items_update_invalid_options`	+ Added	Error
Returned when proration_billing_mode is not do_not_bill for item changes while trialing.