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:
- 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
andnext_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:
Create a request that includes your new trial end date as the
next_billed_at
date, withdo_not_bill
as the proration billing mode.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.
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
.
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.
12341{
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.
Paddle ID of the subscription entity to work with.
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.
12345678910111213141516171819201{
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:
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.
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.
Paddle ID of the subscription entity to work with.
Include related entities in the response. Use a comma-separated list to specify multiple entities.
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.
171819202122232425262728293031323334353617 "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.
Paddle ID of the subscription entity to work with.
Response
If successful, Paddle returns a copy of the activated subscription entity.
12345678910111213141516171819201{
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
subscription.updated | Occurs when the next_billed_at date for a subscription is changed. |
subscription.activated | Occurs 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. |