Paddle Billing
Search

Extend or activate a trial

Extend a trial to give customers longer to evaluate, or cut a trial short to transition a customer to paying.

Trials let customers try your app or service before paying for it. You can extend trials to give customers more time to evaluate your app, or activate a subscription before a trial is up to transition a customer to paying.

Making it as easy as possible for trialing customers to transition to a paid plan is a simple way to reduce your customer acquisition cost.

Change the items list against a subscription to add or remove items, update quantities, and bill for one-time charges. See: Work with trials

How it works

When customers complete checkout for recurring items with a trial period, Paddle creates a subscription with the status trialing. The customer isn't charged right away. Instead, they're charged on the next_billed_at date against the subscription.

When the next_billed_at date elapses, Paddle charges the payment method on file and the subscription changes to active. The current_billing_period for trialing subscriptions is based on the trial period. On activation, it's updated so that it's based on the billing_cycle.

You can extend a trial by changing the next_billed_at date against a subscription to a date after this date.

You can cut a trial period short by either:

Both options work for automatically-collected subscriptions. The activate a trialing subscription operation only works for automatically-collected subscriptions, so you should move the billing date for manually-collected subscriptions.

Since customers aren't yet paying, proration doesn't apply when changing billing dates for a trial. You must use do_not_bill as the proration_billing_mode when sending requests.

Only the items and next_billed_at fields can be updated for a subscription in trial. You cannot update other fields against a subscription until it's activated.

Before you begin

To extend or activate 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.

Extend or cut short a trial

Extend or cut short a trial using the API in two steps:

  1. Build a request

    Create a request that includes your new trial end date as the next_billed_at date, with do_not_bill as the proration billing mode.

  2. Update the subscription

    Send the request to apply the changes. Paddle updates the subscription.

Build request

Build a request that includes next_billed_at with the date and time the trial should end.

The new date and time must be at least 30 minutes after your request. You can't make changes to a subscription if the next billing period is within 30 minutes.

next_billed_atstring<date-time>

RFC 3339 datetime string of when this subscription is next scheduled to be billed.

Along with the next_billed_at field, you must include the proration_billing_mode field to tell Paddle how to bill for the changed date.

The only allowed value when changing the next_billed_at for a trialing subscription is do_not_bill.

proration_billing_modestring

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.

Request

This example sets the next billing date for a subscription in trial. It includes do_not_bill as the proration billing mode.

Update subscription

Send a PATCH request to the /subscriptions/{subscription_id} endpoint with the request you built.

Response

If successful, Paddle returns a copy of the updated subscription entity.

next_billed_at is updated for the subscription and against any items. Paddle also updates the current_billing_period and items[].trial_dates.ends_at so you can see total trial period for a subscription.

Activate a trialing subscription

Activate a subscription to cut the trial period short and start charging a customer for it.

Only automatically-collected subscriptions can be activated using the activate a subscription operation. For manually-collected subscriptions, follow the steps to extend or cut short a trial (above).

Activate a trialing subscription using the API in two steps:

  1. Preview charging for the subscription

    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 a customer if you let them activate a subscription in your frontend.

  2. Activate the subscription

    Send a request to activate the subscription. Paddle updates the subscription and starts charging for it.

Preview charging

Send a GET request to the /subscriptions/{subscription_id} endpoint, using the include parameter with the next_transaction and recurring_transaction_details values.

Response

If successful, Paddle returns a copy of your subscription entity including:

  • next_transaction: An object with a preview of the next transaction for this subscription. May include charges that are not 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 might like to present a customer with charging information in your frontend if you provide a way for them to activate a trialing subscription themselves.

Activate subscription

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

You do not need to include a request body. The subscription is activated immediately.

POSThttps://api.paddle.com/subscriptions/{subscription_id}/activate
subscription_idstring

Paddle ID of the subscription entity to work with.

Response

If successful, Paddle returns a copy of the activated subscription entity.

Events

subscription.updatedOccurs when the next_billed_at date for a subscription is changed.
subscription.activatedOccurs when the trial end date for a subscription elapses and it becomes active, or when the active a trialing subscription operation is used to activate a subscription immediately.

Related pages