Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
How subscriptions work
Recurring pricing models
Get started
Quickstart
Integrate a SaaS business
Embed a pricing table
Design an integration
Build a subscriptions integration
Migrate subscriptions to Stripe
Billing resources
Coupons
Customers
Subscriptions
Subscription invoices
Manage subscriptions
Change subscriptions
Usage-based billing
Use trial periods
Set payment methods
Subscriptions with multiple products
Set subscription quantities
Subscription webhooks
Schedule subscriptions
Tax
Sales-led B2B billing
Integrate with Salesforce
Manage recurring revenue
Revenue recognition
Revenue recovery
Subscription metrics
Customer management
Overview
Set up the the no-code customer portal
Set up the customer portal with the API
Configure the customer portal
Testing
Test your integration
Test clocks
Strong Customer Authentication (SCA)
Invoices API updates
Testing
Billing
·
HomePaymentsSubscriptions

Using trial periods on subscriptions

Delay payments on active subscriptions using trial periods.

You can start a customer’s subscription with a free trial period by providing a trial_end argument when creating the subscription:

Command Line
curl https://api.stripe.com/v1/subscriptions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d customer=
{{CUSTOMER_ID}}
\ -d "items[0][price]"=
{{PRICE_ID}}
\ -d trial_end=1610403705

The trial_end parameter takes a timestamp indicating the exact moment the trial should end. When creating a subscription, you can alternatively use the trial_period_days argument: an integer representing the number of days the trial should last, from the current moment.

When creating a subscription with a trial period, no payment method is required for the customer. An immediate invoice is still created, but for $0.

Intra-subscription trials

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 cycle.

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 cycle 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
curl https://api.stripe.com/v1/subscriptions/
{{SUBSCRIPTION_ID}}
\ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d trial_end=now

Combining trials with billing cycle anchor

As of API version 2018-02-05, you can also combine trials with billing_cycle_anchor, resulting in a free period followed by a prorated period, leading into a fixed billing cycle.

For example, suppose it’s the 15th of the month and you want to give your customer a free 7 day trial (until the 22nd), and then start normal billing on the 1st. You can do this through the API by combining trials with billing_cycle_anchor. (This isn’t currently available through the Dashboard.)

In this example, the customer gets an invoice for a prorated amount on the 22nd (for the period until the 1st). Then, on the 1st, they’ll be invoiced again for the full amount, and again on the 1st of the following month, and so on.

Command Line
curl https://api.stripe.com/v1/subscriptions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d customer=
{{CUSTOMER_ID}}
\ -d "items[0][price]"=
{{PRICE_ID}}
\ -d trial_end=1610403705 \ -d billing_cycle_anchor=1611008505

Combining trials with usage-based billing

You can use trial periods for subscriptions with usage-based billing. During the trial period, any usage accrued doesn’t count toward the total charged to the customer at the end of the billing cycle. After the trial period ends, usage accrues and is billed at the end of the next billing cycle.

Trials and aggregate usage

If you use the aggregate_usage parameter and set the behavior to last_ever, your customer will be billed for the last usage record if it falls within the trial period, even if the usage occurred during the trial period.

For example, if you provide file storage you might want to offer a month of free storage, but then charge for the first month if the customer continues to store files with your service.

Metered billing with paused subscriptions

Subscriptions that have subscription items with metered pricing bill in arrears because we need the total usage to determine the amount to bill. Paused subscriptions won’t allow usage events to be created for attached subscription items. Because it’s possible for you to resume a subscription in the middle of a billing period while leaving the billing cycle anchor unchanged, we support invoicing for the usage events with a timestamp after the subscription resumes.

Combining trials with add_invoice_items

Trial periods for subscriptions can be combined with one time prices and add_invoice_items. This may happen if you want to charge a one time fee or add on at the same time as starting a trial. Note that doing this will cause an invoice to be cut immediately for the amount of the one time item at the beginning of the trial.

Compliance requirements for trials and promotions

You must comply with card network requirements when offering trials, whether they’re free or not. This includes scenarios like free trials or charging customers a reduced price for the first few months and then automatically charging them your normal rate. When using our trials features, you can enable messaging settings in the Stripe Dashboard to help you meet the requirements.

If you notify users of successful payments, Stripe automatically displays information about the trial and the cancellation URL in those notifications.

If you don’t use these settings, you’re still responsible for complying with the requirements.

When customer emails are enabled, a reminder is sent seven days before a trial ends. If a trial is shorter than seven days, the reminder email is sent as soon as the trial begins. If trials are renewed, a reminder email is resent.

If both trial reminders and subscription renewal reminders are enabled during a trial, customers only receive the trial ending reminder. Renewal emails are then sent for subsequent billing periods.

The cancellation policy link is a URL that is displayed on customer receipts, along with other trial information. This information is included for all card payments. The cancellation URL is also included in the reminder email that is sent to customers seven days before their trial ends.

For statement descriptors, if you manually set the statement descriptor on the invoice, the trial text isn’t appended so you need to add it. If you use product statement descriptors, the trial text is appended automatically. If your statement descriptor is greater than 10 characters, make sure it still makes sense to your customers with the trial text appended. There is a 22 character limit so anything after the 10th character is overwritten with * TRIAL OVER.

If you don’t manually set the statement descriptor or use product statement descriptors, the trial text is appended to your account’s statement descriptor. If needed, you can set up a shortened descriptor to ensure the trial text displays correctly.

Meeting requirements without using Stripe’s features

If you offer trials or promotions without using our trials features, you still need to comply with the requirements. You can listen for the invoice.upcoming event to determine when to send email notifications. To add text to your statement descriptor that indicates the promotion is over:

  • Listen for the customer.subscription.updated event
  • Check to see if a trial or promotion has ended
  • Update the statement descriptor on the subscription’s latest_invoice

You need to update the latest invoice within an hour of its creation while it’s still in draft status.

Create free trials without collecting payment method

You can sign customers up for a free trial of a subscription without collecting their payment details. At the end of the trial period you specify, use Stripe to:

  • Pause and resume renewals
  • Configure a reminder email to collect a customer’s payment details
  • Provide more accurate revenue analytics and Dashboard options

Configure free trials

Use the Stripe API, Dashboard, or Checkout to create free trials of a subscription without collecting payment details from your customers. At the end of the trial period you specify, use Stripe to configure a reminder email to collect a customer’s payment details.

Use the API to sign up customers for a free trial of a subscription without collecting their payment details with the following calls:

Command Line
curl https://api.stripe.com/v1/subscriptions \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d customer=
{{CUSTOMER_ID}}
\ -d "items[0][price]"=
{{PRICE_ID}}
\ -d trial_period_days=30 \ -d "payment_settings[save_default_payment_method]"=on_subscription \ -d "trial_settings[end_behavior][missing_payment_method]"=pause

To update existing subscriptions, use the following API calls:

Command Line
curl https://api.stripe.com/v1/subscriptions/
{{SUBSCRIPTION_ID}}
\ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -d "trial_settings[end_behavior][missing_payment_method]"=pause

Alternatively, use the missing_payment_method=cancel option to cancel the subscription immediately if a free trial ends with no payment method attached. Although this might simplify your integration, status=canceled is a final state, unlike status=paused. Canceled subscriptions can’t be resumed.

Webhook events

Events are triggered every time a free trial is changed. Make sure that your integration properly handles the events. For example, you might want to email a customer before a free trial ends. Learn more about subscription webhook events.

The following table describes the events that trigger before a free trial ends, when a trial subscription pauses, and when a subscription is resumed and becomes active.

EventDescriptionUse case
customer.subscription.resumedSent when a subscription is no longer paused. When you receive this event, grant the customer access to the product if access was revoked while the subscription was paused.Paused subscriptions are converted into active subscriptions after being resumed. Resuming a subscription might generate an invoice and corresponding Payment Intent that must be paid before the subscription moves out of the paused state.
customer.subscription.pausedSent when a subscription is fully paused. Invoicing won’t occur until the subscription resumes. When you receive this event, you can revoke the customer’s access to the product until they add a payment method and the subscription resumes.Configure the subscription to automatically pause when the trial ends without a payment method. Stop providing access to your product in response to this webhook. The subscription is paused until explicitly resumed.
customer.subscription.trial_will_endSent three days before the trial period ends. If the trial is less than 3 days, this event is triggered.Configure the subscription to automatically send an email to your customer 3 days before the trial period ends. If no payment method is provided, stop providing access to your product when the subscription pauses. The subscription is paused until explicitly resumed.

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:

  1. Listen to the customer.subscription.trial_will_end event.
  2. If the subscription doesn’t have a default payment method, get the customer’s email using the Customers API and send them a message with a link to your site. It’s helpful to embed the customer ID in the email. For example: https://example.com?...&customer={{CUSTOMER_ID}}.
  3. When the customer enters your site, create a Customer Portal session using the customer ID from the previous step.
  4. 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.

Send an email reminder before the trial ends

To send a reminder email prior to the end of the trial, select the Link to a Stripe-hosted page option in the Subscriptions and emails setting. The reminder email contains a link for the customer to add or update their payment details. We don’t send free trial reminder emails in test mode. Learn more about how to manage free trial messages within the customer email.

Use the customer.subscription.trial_will_end event to send your own hosted emails to customers. After you see the event in the Dashboard, it’s confirmed that your email has been sent.

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.

Pause subscriptions when trials end without collecting a payment method

If your customer hasn’t provided payment by the time their trial ends, configure your subscriptions to pause. When subscriptions are paused, they don’t create new invoices and the current billing period remains the same.

Use the trial_settings.end_behavior.missing_payment_method field when creating or updating a subscription to configure behavior at the end of a trial. Set missing_payment_method=pause to pause the subscription when it reaches the end of a trial without an available payment method.

Set missing_payment_method=create_invoice to invoice at the end of the trial, even if no payment method is present. If a payment method isn’t provided when the invoice finalizes, the subscription moves into past_due.

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 state, 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 Stripe API, Dashboard, Customer Portal, or Hosted Invoice Page to resume a paused subscription.

When a paused subscription resumes, resumption of the subscription begins immediately. The resume endpoint enables you to resume a subscription and optionally change the billing_cycle_anchor date or create prorations.

For a billing_cycle_anchor value of unchanged, we create a debit proration for the partial period between proration_date (the default is now) and the end of the current billing period (unless proration_behavior=none). This also creates an invoice for the current period if proration_behavior=always_invoice.

Use the resume endpoint to resume a paused subscription. A payment method doesn’t need to be supplied on the subscription before you can resume (for example, if you want to generate or view the invoice prior to a customer providing payment), but the invoice needs to be paid before the subscription is reactivated. The invoice becomes automatically void after 23 hours if the associated payment intent doesn’t have a payment method attached and isn’t confirmed.

When you reactivate a subscription, the current_period_start and current_period_end endpoints advance to surround the current time. If billing_cycle_anchor=now, then current_period_start == now, which starts a new cycle, similar to converting after the trial ends.

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 a subscription_resume_at.

See also

  • Products and prices
  • Prices
  • Subscriptions
  • Managing subscription billing cycles
Was this page helpful?
Questions? Contact us.
Watch our developer tutorials.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Combining trials with billing cycle anchor
Combining trials with usage-based billing
Combining trials with add_invoice_items
Compliance requirements for trials and promotions
Create free trials without collecting payment method
See also
Stripe Shell
Test mode
▗▄ ▄▟█ █▀▀ ▗▟████▙▖ ██████ ███▗▟█ ███ ███▗▟██▙▖ ▗▟█████▙▖ ███▖ ▀▀ ███ ███▀▀▀ ███ ███▀ ███ ███ ███ ▝▜████▙▖ ███ ███ ███ ███ ███ █████████ ▄▄ ▝███ ███ ▄ ███ ███ ███▄ ███ ███ ▄▄ ▝▜████▛▘ ▝▜███▛ ███ ███ ███▝▜██▛▘ ▝▜█████▛▘ ███ ▀▘
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to Stripe docs and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$