Extend or activate a trial

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:

• Changing the next_billed_at date against a subscription to an earlier date.
• Sending a request to the /subscriptions/{subscription_id}/activate endpoint to activate a subscription immediately.

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 want 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

Request

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

1
2
3
4
1{
2  "next_billed_at": "2023-10-01T00:00:00Z",
3  "proration_billing_mode": "do_not_bill"
4}

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "sub_01h90n6j4k325zxf9rasr9rsb3",
4    "status": "trialing",
5    "customer_id": "ctm_01h84cjfwmdph1k8kgsyjt3k7g",
6    "address_id": "add_01h90n5k7r3gzznv46h2nta7z0",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2023-08-29T12:44:51.731Z",
10    "updated_at": "2023-08-29T12:53:28.538Z",
11    "started_at": "2023-08-29T12:44:51.731Z",
12    "first_billed_at": null,
13    "next_billed_at": "2023-10-01T00:00:00Z",
14    "paused_at": null,
15    "canceled_at": null,
16    "collection_mode": "automatic",
17    "billing_details": null,
18    "current_billing_period": {
19      "starts_at": "2023-08-29T12:44:51.731Z",
20      "ends_at": "2023-10-01T00:00:00Z"

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.

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
17    "billing_details": null,
18    "current_billing_period": {
19      "starts_at": "2023-08-29T12:44:51.731Z",
20      "ends_at": "2023-10-01T00:00:00Z"
21    },
22    "billing_cycle": {
23      "frequency": 1,
24      "interval": "year"
25    },
26    "recurring_transaction_details": {
27      "tax_rates_used": [
28        {
29          "tax_rate": "0.08875",
30          "totals": {
31            "subtotal": "1000000",
32            "discount": "0",
33            "tax": "88750",
34            "total": "1088750"
35          }
36        }

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.

Response

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "sub_01hv915hmgnwqd9n5yxgy8t60c",
4    "status": "active",
5    "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j",
6    "address_id": "add_01hv914saqwe9wk1sbxyy9q7kq",
7    "business_id": null,
8    "currency_code": "USD",
9    "created_at": "2024-04-12T11:30:29.648Z",
10    "updated_at": "2024-04-12T11:31:10.027Z",
11    "started_at": "2024-04-12T11:30:29.637Z",
12    "first_billed_at": "2024-04-12T11:31:09.996Z",
13    "next_billed_at": "2024-05-12T11:31:09.996Z",
14    "paused_at": null,
15    "canceled_at": null,
16    "collection_mode": "automatic",
17    "billing_details": null,
18    "current_billing_period": {
19      "starts_at": "2024-04-12T11:31:09.996Z",
20      "ends_at": "2024-05-12T11:31:09.996Z"

Events

Related pages