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 CAC (customer acquisition cost).
Change the items list against a subscription to add or remove items, update quantities, and bill for one-time charges. To learn more, 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_atdate against a subscription to an earlier date. - Sending a request to the
/subscriptions/{subscription_id}/activateendpoint 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 can't 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
Send a PATCH request to the /subscriptions/{subscription_id} endpoint to extend a trial.
In your request, include:
next_billed_atwith the new trial end date. Must be at least 30 minutes from now.proration_billing_modeset todo_not_bill, which is the only allowed value for trialing subscriptions.
Paddle updates the next_billed_at date for the subscription and items, and current_billing_period and items[].trial_dates.ends_at.
{ "next_billed_at": "2023-10-01T00:00:00Z", "proration_billing_mode": "do_not_bill"}{ "data": { "id": "sub_01h90n6j4k325zxf9rasr9rsb3", "status": "trialing", "customer_id": "ctm_01h84cjfwmdph1k8kgsyjt3k7g", "address_id": "add_01h90n5k7r3gzznv46h2nta7z0", "business_id": null, "currency_code": "USD", "created_at": "2023-08-29T12:44:51.731Z", "updated_at": "2023-08-29T12:53:28.538Z", "started_at": "2023-08-29T12:44:51.731Z", "first_billed_at": null, "next_billed_at": "2023-10-01T00:00:00Z", "paused_at": null, "canceled_at": null, "collection_mode": "automatic", "billing_details": null, "current_billing_period": { "starts_at": "2023-08-29T12:44:51.731Z", "ends_at": "2023-10-01T00:00:00Z" }, "billing_cycle": { "frequency": 1, "interval": "year" }, "scheduled_change": null, "items": [ { "status": "trialing", "quantity": 10, "recurring": true, "created_at": "2023-08-29T12:44:51.731Z", "updated_at": "2023-08-29T12:53:28.537Z", "previously_billed_at": null, "next_billed_at": "2023-10-01T00:00:00Z", "trial_dates": { "starts_at": "2023-08-29T12:44:51.731Z", "ends_at": "2023-10-01T00:00:00Z" }, "price": { "id": "pri_01h84cdy3xatsp16afda2gekzy", "product_id": "pro_01h84cd36f900f3wmpdfamgv8w", "description": "Annual plan", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "year" }, "trial_period": { "frequency": 10, "interval": "day" }, "unit_price": { "amount": "0", "currency_code": "USD" } } } ], "custom_data": null, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h90n6j4k325zxf9rasr9rsb3/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h90n6j4k325zxf9rasr9rsb3/cancel" }, "discount": null }, "meta": { "request_id": "2ec9fe96-bfc6-485b-8804-9e6950a32b42" }}Activate a trialing subscription
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.
Activate a subscription to cut the trial period short and start charging a customer for it.
Activate a subscription using the API in two steps:
- Preview charging Optional
Preview how much the customer is going to be charged on activation. Present this to customers if you offer in-app activation. - Activate subscription
Send a request to activate a subscription immediately.
Preview charging Optional
Send a GET request to the /subscriptions/{subscription_id} endpoint, using the include query parameter with the next_transaction and recurring_transaction_details values to get a preview of what the customer is going to be charged when you activate the subscription.
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 in-app activation.
{ "data": { "id": "sub_01h90n6j4k325zxf9rasr9rsb3", "status": "trialing", "customer_id": "ctm_01h84cjfwmdph1k8kgsyjt3k7g", "address_id": "add_01h90n5k7r3gzznv46h2nta7z0", "business_id": null, "currency_code": "USD", "created_at": "2023-08-29T12:44:51.731Z", "updated_at": "2023-08-29T12:53:28.538Z", "started_at": "2023-08-29T12:44:51.731Z", "first_billed_at": null, "next_billed_at": "2023-10-01T00:00:00Z", "paused_at": null, "canceled_at": null, "collection_mode": "automatic", "billing_details": null, "current_billing_period": { "starts_at": "2023-08-29T12:44:51.731Z", "ends_at": "2023-10-01T00:00:00Z" }, "billing_cycle": { "frequency": 1, "interval": "year" }, "recurring_transaction_details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "1000000", "discount": "0", "tax": "88750", "total": "1088750" } } ], "totals": { "subtotal": "1000000", "tax": "88750", "discount": "0", "total": "1088750", "fee": null, "credit": "0", "balance": "1088750", "grand_total": "1088750", "earnings": null, "currency_code": "USD", "exchange_rate": "1" }, "line_items": [ { "price_id": "pri_01h84cdy3xatsp16afda2gekzy", "quantity": 10, "totals": { "subtotal": "1000000", "tax": "88750", "discount": "0", "total": "1088750" }, "product": { "id": "pro_01h84cd36f900f3wmpdfamgv8w", "name": "ChatApp Essential", "description": "Our starter plan — ideal for small teams for who are just starting out.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "100000", "discount": "0", "tax": "8875", "total": "108875" } } ] }, "next_transaction": { "billing_period": { "starts_at": "2023-10-01T00:00:00Z", "ends_at": "2024-10-01T00:00:00Z" }, "details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "1000000", "discount": "0", "tax": "88750", "total": "1088750" } } ], "totals": { "subtotal": "1000000", "tax": "88750", "discount": "0", "total": "1088750", "fee": null, "credit": "0", "balance": "1088750", "grand_total": "1088750", "earnings": null, "currency_code": "USD", "exchange_rate": "1" }, "line_items": [ { "price_id": "pri_01h84cdy3xatsp16afda2gekzy", "quantity": 10, "totals": { "subtotal": "1000000", "tax": "88750", "discount": "0", "total": "1088750" }, "product": { "id": "pro_01h84cd36f900f3wmpdfamgv8w", "name": "ChatApp Essential", "description": "Our starter plan — ideal for small teams for who are just starting out.", "tax_category": "standard", "image_url": "https://paddle-sandbox.s3.amazonaws.com/user/10889/2nmP8MQSret0aWeDemRw_icon1.png", "status": "active" }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "100000", "discount": "0", "tax": "8875", "total": "108875" } } ] }, "adjustments": [] }, "scheduled_change": null, "items": [ { "status": "trialing", "quantity": 10, "recurring": true, "created_at": "2023-08-29T12:44:51.731Z", "updated_at": "2023-08-29T12:53:28.537Z", "previously_billed_at": null, "next_billed_at": "2023-10-01T00:00:00Z", "trial_dates": { "starts_at": "2023-08-29T12:44:51.731Z", "ends_at": "2023-10-01T00:00:00Z" }, "price": { "id": "pri_01h84cdy3xatsp16afda2gekzy", "product_id": "pro_01h84cd36f900f3wmpdfamgv8w", "description": "Annual plan", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "year" }, "trial_period": { "frequency": 10, "interval": "day" }, "unit_price": { "amount": "0", "currency_code": "USD" } } } ], "custom_data": null, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01h90n6j4k325zxf9rasr9rsb3/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01h90n6j4k325zxf9rasr9rsb3/cancel" }, "discount": null }, "meta": { "request_id": "a587bb7e-7f1f-418b-ba83-201768796d5b" }}Activate subscription
Send a POST request to the /subscriptions/{subscription_id}/activate endpoint to activate a subscription immediately. No request body needed.
Paddle activates the subscription immediately.
{ "data": { "id": "sub_01hv915hmgnwqd9n5yxgy8t60c", "status": "active", "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j", "address_id": "add_01hv914saqwe9wk1sbxyy9q7kq", "business_id": null, "currency_code": "USD", "created_at": "2024-04-12T11:30:29.648Z", "updated_at": "2024-04-12T11:31:10.027Z", "started_at": "2024-04-12T11:30:29.637Z", "first_billed_at": "2024-04-12T11:31:09.996Z", "next_billed_at": "2024-05-12T11:31:09.996Z", "paused_at": null, "canceled_at": null, "collection_mode": "automatic", "billing_details": null, "current_billing_period": { "starts_at": "2024-04-12T11:31:09.996Z", "ends_at": "2024-05-12T11:31:09.996Z" }, "billing_cycle": { "frequency": 1, "interval": "month" }, "scheduled_change": null, "items": [ { "status": "active", "quantity": 10, "recurring": true, "created_at": "2024-04-12T11:30:29.648Z", "updated_at": "2024-04-12T11:31:10.029Z", "previously_billed_at": "2024-04-12T11:31:09.996Z", "next_billed_at": "2024-05-12T11:31:09.996Z", "trial_dates": { "starts_at": "2024-04-12T11:30:29.637Z", "ends_at": "2024-04-12T11:31:09.996Z" }, "price": { "id": "pri_01hv0vax6rv18t4tamj848ne4d", "product_id": "pro_01htz88xpr0mm7b3ta2pjkr7w2", "type": "standard", "description": "Monthly (per seat) with 14 day trial", "name": "Monthly (per seat)", "tax_mode": "account_setting", "billing_cycle": { "frequency": 1, "interval": "month" }, "trial_period": { "frequency": 14, "interval": "day", "requires_payment_method": false }, "unit_price": { "amount": "500", "currency_code": "USD" }, "unit_price_overrides": [ { "country_codes": ["IE", "FR", "DE"], "unit_price": { "amount": "700", "currency_code": "EUR" } }, { "country_codes": ["GB"], "unit_price": { "amount": "600", "currency_code": "GBP" } } ], "custom_data": null, "status": "active", "quantity": { "minimum": 1, "maximum": 100 }, "import_meta": null, "created_at": "2024-04-09T07:14:38.424504Z", "updated_at": "2024-04-09T07:15:53.950721Z" }, "product": { "id": "pro_01htz88xpr0mm7b3ta2pjkr7w2", "name": "AeroEdit for learner pilots", "type": "standard", "tax_category": "standard", "description": "Essential tools for student pilots to manage flight logs, analyze performance, and plan routes, and ensure compliance. Valid student pilot certificate from the FAA required.", "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png", "custom_data": { "features": { "aircraft_performance": true, "compliance_monitoring": false, "flight_log_management": true, "payment_by_invoice": false, "route_planning": true, "sso": false }, "suggested_addons": [ "pro_01h1vjes1y163xfj1rh1tkfb65", "pro_01gsz97mq9pa4fkyy0wqenepkz" ], "upgrade_description": null }, "status": "active", "import_meta": null, "created_at": "2024-04-08T16:22:16.024Z", "updated_at": "2024-04-08T16:27:59.074Z" } } ], "custom_data": null, "management_urls": { "update_payment_method": "https://buyer-portal.paddle.com/subscriptions/sub_01hv915hmgnwqd9n5yxgy8t60c/update-payment-method", "cancel": "https://buyer-portal.paddle.com/subscriptions/sub_01hv915hmgnwqd9n5yxgy8t60c/cancel" }, "discount": null, "import_meta": null }, "meta": { "request_id": "8e6362d5-caaa-43d9-8ec5-f912c35b697d" }}Events
subscription.updated | Occurs when a subscription is updated. |
subscription.activated | Occurs when a subscription becomes active. |