Billing
Start with a use case
Manage subscriptions
Add payment methods
Invoice customers
Revenue recognition
Sign in
Support
Sign in
Sign up
Billing
Additional features
Using trial periods
HomePaymentsBillingAdditional features

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:

curl https://api.stripe.com/v1/subscriptions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d customer=cus_4fdAW5ftNQow1a \
  -d "items[0][price]"=price_CBb6IXqvTLXp3f \
  -d trial_end=1604246507

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

subscription = Stripe::Subscription.create({
  customer: 'cus_4fdAW5ftNQow1a',
  items: [
    {
      price: 'price_CBb6IXqvTLXp3f',
    },
  ],
  trial_end: 1604246507,
})

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

subscription = stripe.Subscription.create(
  customer='cus_4fdAW5ftNQow1a',
  items=[
    {
      'price': 'price_CBb6IXqvTLXp3f',
    },
  ],
  trial_end=1604246507,
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

$subscription = \Stripe\Subscription::create([
    'customer' => 'cus_4fdAW5ftNQow1a',
    'items' => [
      [
        'price' => 'price_CBb6IXqvTLXp3f',
      ],
    ],
    'trial_end' => 1604246507,
]);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

SubscriptionCreateParams params =
  SubscriptionCreateParams.builder()
    .setCustomer("cus_4fdAW5ftNQow1a")
    .addItem(
      SubscriptionCreateParams.Item.builder()
        .setPrice("price_CBb6IXqvTLXp3f")
        .build())
    .setTrialEnd(1604246507L)
    .build();

Subscription subscription = Subscription.create(params);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const subscription = await stripe.subscriptions.create({
  customer: 'cus_4fdAW5ftNQow1a',
  items: [
    {
      price: 'price_CBb6IXqvTLXp3f',
    },
  ],
  trial_end: 1604246507,
});

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

items := []*stripe.SubscriptionItemsParams{
  {
    Price: stripe.String("price_CBb6IXqvTLXp3f"),
  },
}
params := &stripe.SubscriptionParams{
  Customer: stripe.String("cus_4fdAW5ftNQow1a"),
  Items: items,
  TrialEnd: stripe.Int64(1604246507),
}
subscription, _ := sub.New(params)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var items = new List<SubscriptionItemOptions> {
    new SubscriptionItemOptions {Price = "price_CBb6IXqvTLXp3f"}
};
var options = new SubscriptionCreateOptions {
    Customer = "cus_4fdAW5ftNQow1a",
    Items = items,
    TrialEnd = DateTimeOffset.FromUnixTimeSeconds(1604246507).UtcDateTime,
};
var service = new SubscriptionService();
Subscription subscription = service.Create(options);

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.

Three days before the trial period is up, a customer.subscription.trial_will_end event is sent to your webhook endpoint. You can use that notification as a trigger to take any necessary actions, such as informing the customer that billing is about to begin.

When the trial ends, a new billing cycle starts for the customer. Once the trial period is up, Stripe generates an invoice and sends an invoice.created event notification. Approximately an hour later, Stripe attempts to charge that invoice.

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:

curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d trial_end=now

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::Subscription.update(
  'sub_49ty4767H20z6a',
  {
    trial_end: 'now',
  }
)

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.Subscription.modify('sub_49ty4767H20z6a',
  trial_end='now',
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\Subscription::update('sub_49ty4767H20z6a', [
    'trial_end' => 'now',
]);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Subscription subscription = Subscription.retrieve("sub_49ty4767H20z6a");

SubscriptionUpdateParams params =
  SubscriptionUpdateParams.builder()
    .setTrialEnd(SubscriptionUpdateParams.TrialEnd.NOW)
    .build();

subscription.update(params);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.subscriptions.update('sub_49ty4767H20z6a', {
  trial_end: 'now',
});

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.SubscriptionParams{
  TrialEndNow: stripe.Bool(true),
}
subscription, _ := sub.Update("sub_49ty4767H20z6a", params)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new SubscriptionUpdateOptions {
    TrialEnd = SubscriptionTrialEnd.Now,
};
var service = new SubscriptionService();
Subscription subscription = service.Update("sub_49ty4767H20z6a", options);

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 is 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 is not currently available through the Dashboard.)

In this example, the customer will be invoiced a prorated amount on the 22nd (for the period until the 1st). Then, on the 1st, they will be invoiced again for the full amount, and again on the 1st of the following month, etc.

curl https://api.stripe.com/v1/subscriptions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d customer=cus_4fdAW5ftNQow1a \
  -d "items[0][price]"=price_CBb6IXqvTLXp3f \
  -d trial_end=1604246507 \
  -d billing_cycle_anchor=1604851307

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

subscription = Stripe::Subscription.create({
    customer: 'cus_4fdAW5ftNQow1a',
    items: [{price: 'price_CBb6IXqvTLXp3f'}],
    trial_end: 1604246507,
    billing_cycle_anchor: 1604851307,
})

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

subscription = stripe.Subscription.create(
  customer='cus_4fdAW5ftNQow1a',
  items=[{'price': 'price_CBb6IXqvTLXp3f'}],
  trial_end=1604246507,
  billing_cycle_anchor=1604851307,
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

$subscription = \Stripe\Subscription::create([
    'customer' => 'cus_4fdAW5ftNQow1a',
    'items' => [['price' => 'price_CBb6IXqvTLXp3f']],
    'trial_end' => 1604246507,
    'billing_cycle_anchor' => 1604851307,
]);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

SubscriptionCreateParams params =
  SubscriptionCreateParams.builder()
    .setCustomer("cus_4fdAW5ftNQow1a")
    .addItem(
      SubscriptionCreateParams.Item.builder()
        .setPrice("price_CBb6IXqvTLXp3f")
        .build())
    .setTrialEnd(1604246507L)
    .setBillingCycleAnchor(1604851307L)
    .build();

Subscription subscription = Subscription.create(params);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const subscription = await stripe.subscriptions.create({
  customer: 'cus_4fdAW5ftNQow1a',
  items: [{price: 'price_CBb6IXqvTLXp3f'}],
  trial_end: 1604246507,
  billing_cycle_anchor: 1604851307,
});

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

items := []*stripe.SubscriptionItemsParams{
  {
    Price: stripe.String("price_CBb6IXqvTLXp3f"),
  },
}
params := &stripe.SubscriptionParams{
  Customer: stripe.String("cus_4fdAW5ftNQow1a"),
  Items: items,
  TrialEnd: stripe.Int64(1604246507),
  BillingCycleAnchor: stripe.Int64(1604851307),
}
subscription, _ := sub.New(params)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var items = new List<SubscriptionItemOptions> {
    new SubscriptionItemOptions {Price = "price_CBb6IXqvTLXp3f"}
};
var options = new SubscriptionCreateOptions {
    Customer = "cus_4fdAW5ftNQow1a",
    Items = items,
    TrialEnd = DateTimeOffset.FromUnixTimeSeconds(1604246507).UtcDateTime,
    BillingCycleAnchor = DateTimeOffset.FromUnixTimeSeconds(1604851307).UtcDateTime,
};
var service = new SubscriptionService();
Subscription subscription = service.Create(options);

Combining trials with metered billing

Trial periods for subscriptions with metered billing is also supported. During the trial period, usage accrued on doesn’t count towards the total charged to the customer at the end of the billing cycle. If the aggregation mode is set to last_ever, Stripe bills for that quantity once the trial has ended.

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:

Trial messaging settings

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

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.

Next steps

Now that you understand how to use trial periods, you may want to check out:

Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.
On this page
Combining trials with billing cycle anchor
Combining trials with metered billing
Combining trials with add_invoice_items
Compliance requirements for trials and promotions
Next steps