Configure free trials

You can configure a Checkout Session to start a customer’s subscription with a free trial by passing one of the following parameters:

• subscription_data.trial_period_days, the length (in days) of your free trial.
• subscription_data.trial_end, a Unix timestamp representing the end of the trial period.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=subscription \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel" \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "subscription_data[trial_period_days]"=30

Free trials without collecting a payment method

By default, Checkout Sessions collect a payment method to use after the trial ends. You can sign customers up for free trials without collecting payment details by passing payment_method_collection=if_required.

Choose whether to cancel or pause the subscription if the customer doesn’t provide a payment method before the trial ends by passing trial_settings.end_behavior.missing_payment_method.

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

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d mode=subscription \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel" \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "subscription_data[trial_period_days]"=30 \
  -d "subscription_data[trial_settings][end_behavior][missing_payment_method]"=cancel \
  -d payment_method_collection=if_required

Collect payment details automatically

Before the trial expires, collect payment details from your customer.

Under Manage free trial messaging in your Subscriptions and emails settings, you can choose to automatically send a reminder email when a customer’s trial is about to expire.

Next, select the Link to a Stripe-hosted page option so 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 a sandbox. Learn more about how to set up free trial reminders.

You must comply with card network requirements when offering trials. Learn more about compliance requirements for trials and promotions.

Collect payment details in the Billing customer portal

You can also send the reminder email yourself, and redirect customers 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 lands on 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.

Your customers can also resume their paused subscription in the customer portal by selecting Start subscription, then adding a payment method. View free trial periods to learn how to configure a subscription to pause or cancel when a free trial ends without a payment method attached.

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.