Legacy
Use free trial periods on subscriptions Legacy
Offer free trial periods on subscriptions using the legacy trial_end parameter.
Legacy
The content below describes a Legacy integration path for offering free trials.
If you’re building a new integration, we recommend that you Configure trial offers on subscriptions.
You can start a customer’s subscription with a free trial period by providing a trial_end argument when creating the subscription:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Use the Accounts v2 API to represent customers
The Accounts v2 API is generally available for Connect users, and in public preview for other Stripe users. If you’re part of the Accounts v2 preview, you need to specify a preview version in your code.
To join the Accounts v2 preview, go to Account previews and features in your Dashboard and enable Reusable payment methods for Global Payouts.
For most use cases, we recommend modelling your customers as customer-configured Account objects instead of using Customer objects.
The trial_end parameter takes a timestamp indicating the exact moment the trial ends. When creating a subscription, you can alternatively use the trial_period_days parameter: an integer representing the number of days the trial lasts, from the current moment. The trial period must be 730 days (2 years) or less. Trial periods are normally applied at the start of a subscription, but you can also use a trial period on an existing subscription to change the subscription’s billing period (cycle).
When creating a subscription with a trial period, you don’t need to add a payment method. An immediate invoice is still created, but the amount is 0 and the Invoice Line descriptions include “Free trial” wording.
When the trial ends, if the subscription status isn’t paused, we generate an invoice and send an invoice.created event notification. Approximately 1 hour later, we attempt to charge that invoice. A new billing period also begins for the customer when the trial ends.
To end a trial early, make an update subscription API call, setting the trial_end value to a new timestamp, or now to end immediately:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Trials with usage-based billing
You can use trial periods for subscriptions with usage-based billing. Stripe doesn’t bill for usage recorded during the trial period, but you can view the usage in the meter event summary for the trial period. After the trial period ends, billing resumes for recorded usage.
Make sure your integration properly monitors and handles webhook events related to trial status changes. A few days before a trial ends and the subscription moves from trialing to active, you receive a customer.subscription.trial_will_end event. When you receive this event, make sure you have a payment method on the customer account to bill them. Optionally, provide advance notification to the customer about the upcoming charge.
Usage-based billing with paused subscriptions
You can send meter events associated with a price on a subscription even while it’s paused, but that usage isn’t invoiced. Future invoices only include meter events that occur after the resume date. If you use legacy usage records, you can’t create new usage records while a subscription is paused.
Adding a new trial to a subscription previously in a trial
You can add a new trial on a non-trialling subscription by updating the subscription while specifying trial_end or updating its associated subscription schedule. You need to specify phases.trial_end for subscriptions.
For most subscriptions that enter a new trial after a previous trial ends, the trial_start field remains set to the start of the first trial. As of API version 2025-04-30, for subscriptions with billing_mode set to flexible, trial_start reflects the beginning of the most recent trial.
Update a subscription in a trial
You can update subscriptions in a trial normally. Adding items to a billing_mode=flexible or billing_mode=classic subscription in a trial generates an invoice for those items with an amount of 0. For billing_mode=classic, the zero-amount invoice might include items that were previously invoiced.
Combining trials with add_invoice_items
You can combine trial periods for subscriptions with one time prices and add_invoice_items. This is useful when you want to charge a one-time fee or add-on at the same time you start a trial. When you do this, Stripe automatically generates an invoice for the one-time charge, even though the trial hasn’t ended yet. The customer pays the one-time amount upfront, while the recurring subscription billing begins after the trial period ends.
Create free trials without collecting payment method
Security tip
Although starting a free trial without a payment method lets your potential customers try your product or service faster, it can also allow spammers to create lots of fake customers, usage, and subscriptions. We recommend carefully considering the sign-up flow here to balance making it easy for real customers and difficult for spam bots to abuse (for example, requiring customers to create a user account and complete a captcha before starting their free trial subscription).
You can sign customers up for a free trial of a subscription without collecting their payment details in the Dashboard, the API, and Checkout. When you create the subscription, you can specify whether to cancel or pause the subscription if the customer didn’t provide a payment method during the trial period. To cancel or pause the subscription, set the trial_settings.end_behavior.missing_payment_method parameter when you create or update the subscription:
- Cancel subscription – If the free trial subscription ends without a payment method, it cancels immediately. You can create another subscription if the customer decides to subscribe to a paid plan in the future. Set missing _ payment _ method=cancel to cancel the subscription when it reaches the end of a trial without an available payment method.
- Pause subscription -If the free trial subscription ends without a payment method, it pauses and doesn’t cycle until it’s resumed. When a subscription is paused, it doesn’t generate invoices (unlike when a subscription’s payment collection is paused). When your customer adds their payment method after the subscription has paused, you can resume the same subscription. The subscription can remain paused indefinitely. Set missing _ payment _ method=pause to pause the subscription when it reaches the end of a trial without an available payment method.
Alternatively, set missing_payment_method=create_invoice to invoice at the end of the trial if no payment method is present. If a payment method isn’t provided when the invoice finalises, the subscription moves into past_due.
Configure reminder emails to collect customer payment details in your free trial messaging settings.
Configure free trials without payment methods to cancel
Use the Dashboard, the API, or Checkout to create free trials of a subscription without collecting payment details from your customers, and to configure your subscription to cancel if the trial ends without a payment method.
Use the Dashboard to sign customers up for a free trial of a subscription without collecting their payment details:
- From the Subscriptions settings of the Dashboard, select +Create subscription .
- After adding your customer and product information, select +Add free trial , then input how many days the free trial lasts.
- Select the Pause or cancel if free trial ends without a payment method option, then select Cancel immediately . If you’re using test clocks , advance to the end of the trial. You won’t see an upcoming invoice for the subscription.
- Listen to the customer. subscription. deleted event that informs you when a subscription cancels at the end of trials without a payment method.
If you provide a payment method or select the Email invoice to customer with link to payment page option, the Pause or cancel if free trial ends without a payment method option won’t be visible.
Configure free trials without payment methods to pause
Use the Dashboard, the API, or Checkout to create free trials of a subscription without collecting payment details from your customers, and to configure your subscription to pause if the trial ends without a payment method.
You can use the Dashboard to sign customers up for a free trial of a subscription without collecting their payment details:
- From the Subscriptions settings of the Dashboard, select +Create subscription .
- After adding your customer and product information, select +Add free trial , then input how many days the free trial lasts.
- Select the Pause or cancel if free trial ends without a payment method option, then select Pause . If you’re using test clocks , advance to the end of the trial. You won’t see an upcoming invoice for the subscription.
- Listen to the customer. subscription. paused event that informs you when a subscription pauses at the end of trials without a payment method.
If you provide a payment method or select the Email invoice to customer with link to payment page option, the Pause or cancel if free trial ends without a payment method option won’t be visible.
Collect payment details from your customer before their trial ends
Configure your subscription to automatically send a reminder email when the customer’s trial is about to expire. You must comply with the card network requirements when offering trials. Learn more about compliance requirements for trials and promotions.
Use the customer portal to collect payment
After you create a subscription for a customer without collecting a payment method, you can redirect them to the Billing customer portal to add their payment details.
First, configure the Billing customer portal to enable your customers to manage their subscriptions.
Next, collect billing information from your customers:
- Listen to the customer.subscription.trial_will_end event.
- If the subscription doesn’t have a default payment method , get the customer’s email from the associated customer-configured Account or Customer . Send the customer a message with a link to your site. Embed the customer ID in the email, for example https://example.com?..&customer={{CUSTOMER_ID}} .
- When the customer enters your site, create a customer portal session using the customer ID from the previous step.
- Redirect the customer to the customer portal, where they can update their subscription with payment details.
Allow customers to reactivate their subscriptions in the customer portal
To enable the subscription of a customer whose trial ended in a paused subscription through the customer portal, enable the free trial without payment method feature when creating a new subscription in the Dashboard.
Convert a trial if customers provide payment information before the trial ends
Subscriptions and upcoming invoices are created at the start of the trial and become active at the end of the trial if the customer provides a payment method.
Configure pausing when a payment method isn’t provided
After a free trial ends, you can configure subscriptions to pause if no default payment method is available for a subscription on a per-subscription basis.
You can update subscriptions while they’re paused. Updates that typically generate prorations (adding items, changing price or plan, changing quantity, and so on) won’t generate proration line items because the customer isn’t being charged while the subscription is paused. If you want to extend a trial after a subscription transitions into a paused status, you must resume the subscription before configuring a trial.
We check default_source and default_payment_method on the subscription and customer to determine whether a subscription is missing a payment method at the end of a trial.
Resume a paused subscription
Use the Dashboard, API, customer portal or hosted invoice page to resume a paused subscription.
To resume a paused subscription in the Dashboard:
- Go to the subscription, click the overflow menu ( ), and select Resume Subscription .
- Click the overflow menu ( ), and select Update Subscription .
- Select Reset billing cycle anchor to now to charge the customer immediately.
- To bill the customer for the prorated amount, click Bill for prorated change amount .
- Click Update subscription .
Invoicing a subscription
While paused, a subscription won’t create an invoice. If you want to continue creating invoices, use pause_collection to stop collecting payments while continuing to invoice and advance billing periods.
To preview the invoice that’s generated when a paused subscription is resumed, specify subscription_details.resume_at.
Combine trials with a specific billing cycle anchor
You can combine trials with billing_cycle_anchor, resulting in a free period followed by a prorated period, leading into a fixed billing period. This capability is available through the API.
For example, if you give a customer a 7-day free trial starting on 15 July and want to start normal billing on 1 August:
- On 15 July 15, you give the customer a 7-day free trial (until 22 July).
- The customer gets an invoice for a prorated amount on 22 July, for the period until 1 August.
- The customer is billed for the full amount on 1 August, then on 1 September, and so on.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
You can also use trial_end to change the billing period for an existing subscription. To learn more, see Change the billing period on existing subscriptions.