Work with trials
Add or remove recurring items, change quantities, and bill for one-time charges for subscriptions in trial.
Trials let customers try your app or service before paying for it. You can update trialing subscriptions to make changes to what a customer is billed for when they transition to a paid plan. You can also bill one-time charges to a subscription for things like data import or setup fees.
We recommend letting customers make changes to a trialing subscription as part of a workflow where they confirm and activate their subscription.
Change the next billing date against a trialing subscription to extend or cut short the trial period. You can also activate a trialing subscription right away using the API. See: Extend or activate a trial
How it works
When customers complete checkout for recurring items with a trial period, or you issue an invoice for items with a trial period, Paddle creates a subscription with the status trialing.
You can make changes to trialing subscriptions to add or remove items, change quantities, and bill for one-time charges. This lets you handle:
Upgrades or downgrades
Replacing items on a subscription to let customers upgrade or downgrade their plan while they're in trial.
Adding, removing, or changing items
Add or remove additional modules, or update quantities for seats or users before going live.
Bill for one-time charges
Charge for things like data import or setup fees during a trial period.
Since customers aren't yet paying, proration doesn't apply when making changes to a trialing subscription. You must use do_not_bill as the proration_billing_mode when sending requests.
Only the
itemsandnext_billed_atfields can be updated for a subscription in trial. You cannot update other fields against a subscription until it's activated.
Before you begin
Get subscription ID
To make changes to items on a trialing subscription, you'll need to get the subscription ID for the subscription you'd like to change.
You can use the status query parameter when listing with the value trialing to get a list of subscriptions in trial.
Extract existing prices
You'll need to extract existing items on a subscription. This is because when updating subscription items, Paddle expects the complete list of items that you'd like to be on the subscription — including existing items. If you don't include an existing item, it's removed from the subscription.
See: Work with lists
Update items
Update items on a trialing subscription to make changes to what a customer is billed for when activated. Replace items on a subscription to upgrade or downgrade; or add, remove, or change items to change how Paddle bills for recurring products like additional modules or seats.
Update items on a trialing subscription using the API in three steps:
Create an
itemslist that includes existing items and new items, withdo_not_billas the proration billing mode.Preview charging for the subscription, including the regular amount the customer pays and any immediate charges. This is optional, but recommended — you should present charge information to your customer about what they'll pay when transition to paid.
Send the request to apply the changes you previewed. Paddle updates the subscription.
Build request
Build a request that includes an items array. Your array should include an object for each item, where each object contains a price ID and a quantity.
Include existing price IDs that you extracted in the previous step, as well as any new items that you'd like to add.
For examples and specific guidance, see:
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 that you'd like to keep.
Paddle ID for the price to add to this subscription, prefixed with pri_.
Quantity of this item to add to the subscription. If updating an existing item and not changing the quantity, you may omit quantity.
Along with your items array, you must include the proration_billing_mode field to tell Paddle how to bill for the added items.
The only allowed value when changing items against a trialing subscription is do_not_bill.
How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing.
For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used.
Preview change
To preview, send a PATCH request to the /subscriptions/{subscription_id}/preview endpoint with the request you built.
Paddle ID of the subscription entity to work with.
Update subscription
To update, send a PATCH request to the /subscriptions/{subscription_id} endpoint with the request you built.
Paddle ID of the subscription entity to work with.
Bill for one-time charges
Bill a one-time charge to a trialing subscription to charge for things like onboarding or setup fees.
Bill for one-time charges using the API in three steps:
Create an
itemslist that includes the one-time charges you'd like to bill for, then choose when to bill for them.Preview charging for the one-time charge. This is optional, but recommended — you should present charge information to your customer.
Send the request to create your one-time charge. Paddle creates a transaction now or in the future.
Build request
Build a request that includes an items array. Your array should include an object for each one-time charge you'd like to add, where each object contains a price ID and a quantity.
You don't need to include existing recurring items on the subscription.
For a complete overview with examples, see: Bill for one-time charges
List of one-time charges to add to this subscription. Only prices where the billing_cycle is null may be added.
Paddle ID for the price to add to this subscription, prefixed with pri_.
Quantity of this item to add to the subscription. If updating an existing item and not changing the quantity, you may omit quantity.
Along with your items array, include effective_from to tell Paddle when to bill for any one-time charges.
You can use any allowed value for trialing subscriptions.
When one-time charges should be billed.
Preview charge
To preview, send a POST request to the /subscriptions/{subscription_id}/charge/preview endpoint with the request you built.
Paddle ID of the subscription entity to work with.
Create one-time charge
To bill for one-time charges, send a POST request to the /subscriptions/{subscription_id}/charge endpoint with the request you built.
Paddle ID of the subscription entity to work with.
