Work with trials

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.

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 pause, 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.
• Pause at the end of the trial period
  Preserve any work a customer did in your app in trial if they're not ready to go live right away.

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.

Before you begin

To make changes to items on a trialing subscription, you'll need to get the subscription ID for the subscription you want to change.

You can use the status query parameter when listing with the value trialing to get a list of subscriptions in trial.

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:

1. Extract existing items
   Get the existing items on the subscription to extract the price.id and quantity for each item.
2. Preview change Optional
   Preview how much the customer is going to be charged on a regular basis. Present this to customers if you offer an in-app workflow to update items.
3. Update subscription
   Send a request to update the subscription with the changes you previewed.

Extract existing items

Send a GET request to the /subscriptions/{subscription_id} endpoint to get the existing items on the subscription. Extract the price.id and quantity for each item in the items array — you'll need these to build your update request.

Preview change Optional

Send a PATCH request to the /subscriptions/{subscription_id}/preview endpoint to preview the changes you're making to the subscription.

In your request, include:

• items: An array of items you want on the subscription. Each item should include a price_id and quantity.
• proration_billing_mode: Set to do_not_bill, which is the only allowed value for trialing subscriptions.

The response includes:

• next_transaction: An object with a preview of the next transaction for this subscription. May include charges that aren't yet billed.
• recurring_transaction_details: An object with a preview of the recurring transaction for this subscription. This is what the customer can expect to be billed when there's no prorated or one-time charges.

You should present this to customers if you offer an in-app workflow to update items.

Update subscription

Send a PATCH request to the /subscriptions/{subscription_id} endpoint to update the subscription.

In your request, include the same body as the preview request.

Paddle updates the subscription.

Bill for one-time charges

Bill a one-time charge to a trialing subscription for things like onboarding or setup fees.

Bill for one-time charges using the API in two steps:

1. Preview charge Optional
   Preview how much the customer is going to be charged for the one-time charge. Present this to customers if you offer a way to bill for one-time charges in your app.
2. Create one-time charge
   Send a request to bill for the one-time charge.

Preview charge Optional

Send a POST request to the /subscriptions/{subscription_id}/charge/preview endpoint to preview the one-time charge.

In your request, include:

• items: An array of one-time items you want to bill for. Each item should include a price_id and quantity. You don't need to include existing recurring items.
• effective_from: Set to immediately to create a transaction right away, or next_billing_period to add charges to the next renewal transaction.

The response includes:

• next_transaction: An object with a preview of the next transaction for this subscription. May include charges that aren't yet billed.
• recurring_transaction_details: An object with a preview of the recurring transaction for this subscription. This is what the customer can expect to be billed when there's no prorated or one-time charges.

You should present this to customers if you offer a way to bill for one-time charges in your app.

Create one-time charge

Send a POST request to the /subscriptions/{subscription_id}/charge endpoint to bill for the one-time charge.

In your request, include the same body as the preview request.

Paddle bills for the one-time charge.

Pause at the end of the trial period

Pause a trialing subscription at the end of the trial period to preserve any work a customer did in your app in trial if they're not ready to go live right away. Paddle bills for the subscription on resume.

Send a POST request to the /subscriptions/{subscription_id}/pause endpoint to pause the subscription.