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 subscribing the customer to a plan:

curl https://api.stripe.com/v1/subscriptions \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d customer=cus_4fdAW5ftNQow1a \
   -d items[0][plan]=plan_CBb6IXqvTLXp3f \
   -d trial_end=1527490525

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

subscription = Stripe::Subscription.create({
    customer: 'cus_4fdAW5ftNQow1a',
    items: [{plan: 'plan_CBb6IXqvTLXp3f'}],
    trial_end: 1527490525,
})

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

subscription = stripe.Subscription.create(
  customer='cus_4fdAW5ftNQow1a',
  items=[{'plan': 'plan_CBb6IXqvTLXp3f'}],
  trial_end=1527490525,
)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$subscription = \Stripe\Subscription::create([
    'customer' => 'cus_4fdAW5ftNQow1a',
    'items' => [['plan' => 'plan_CBb6IXqvTLXp3f']],
    'trial_end' => 1527490525,
]);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> item = new HashMap<>();
item.put("plan", "plan_CBb6IXqvTLXp3f");
Map<String, Object> items = new HashMap<>();
items.put("0", item);
Map<String, Object> params = new HashMap<>();
params.put("customer", "cus_4fdAW5ftNQow1a");
params.put("items", items);
params.put("trial_end", 1527490525);
Subscription subscription = Subscription.create(params);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

const subscription = stripe.subscriptions.create({
  customer: 'cus_4fdAW5ftNQow1a',
  items: [{plan: 'plan_CBb6IXqvTLXp3f'}],
  trial_end: 1527490525,
});

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

items := []*stripe.SubItemsParams{
  {Plan: "plan_CBb6IXqvTLXp3f",},
}
params := &stripe.SubParams{
  Customer: "cus_4fdAW5ftNQow1a",
  Items: items,
  TrialEnd: 1527490525,
}
subscription, _ := sub.New(params)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.SetApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

var items = new List<StripeSubscriptionItemOption> {
    new StripeSubscriptionItemOption {PlanId = "plan_CBb6IXqvTLXp3f"}
};
var options = new StripeSubscriptionCreateOptions {
    Items = items,
    TrialEnd = 1527490525,
};
var service = new StripeSubscriptionService();
StripeSubscription subscription = service.Create("cus_4fdAW5ftNQow1a", 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 emailing your customer that billing for the plan 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_BQokikJOvBiI2HlWgH4olfQ2: \
   -d trial_end=now

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Subscription subscription = Subscription.retrieve("sub_49ty4767H20z6a")
Map<String, Object> params = new HashMap<>();
params.put("trial_end", "now");
subscription.update(params);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

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

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

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

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.SetApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

var options = new StripeSubscriptionUpdateOptions {
    TrialEnd = "now",
};
var service = new StripeSubscriptionService();
StripeSubscription 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_BQokikJOvBiI2HlWgH4olfQ2: \
   -d customer=cus_4fdAW5ftNQow1a \
   -d items[0][plan]=plan_CBb6IXqvTLXp3f \
   -d trial_end=1527490525 \
   -d billing_cycle_anchor=1528095325

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

subscription = Stripe::Subscription.create({
    customer: 'cus_4fdAW5ftNQow1a',
    items: [{plan: 'plan_CBb6IXqvTLXp3f'}],
    trial_end: 1527490525,
    billing_cycle_anchor: 1528095325,
})

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

subscription = stripe.Subscription.create(
  customer='cus_4fdAW5ftNQow1a',
  items=[{'plan': 'plan_CBb6IXqvTLXp3f'}],
  trial_end=1527490525,
  billing_cycle_anchor=1528095325,
)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$subscription = \Stripe\Subscription::create([
    'customer' => 'cus_4fdAW5ftNQow1a',
    'items' => [['plan' => 'plan_CBb6IXqvTLXp3f']],
    'trial_end' => 1527490525,
    'billing_cycle_anchor' => 1528095325,
]);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> item = new HashMap<>();
item.put("plan", "plan_CBb6IXqvTLXp3f");
Map<String, Object> items = new HashMap<>();
items.put("0", item);
Map<String, Object> params = new HashMap<>();
params.put("customer", "cus_4fdAW5ftNQow1a");
params.put("items", items);
params.put("trial_end", 1527490525);
params.put("billing_cycle_anchor", 1528095325);
Subscription subscription = Subscription.create(params);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

const subscription = stripe.subscriptions.create({
  customer: 'cus_4fdAW5ftNQow1a',
  items: [{plan: 'plan_CBb6IXqvTLXp3f'}],
  trial_end: 1527490525,
  billing_cycle_anchor: 1528095325,
});

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

items := []*stripe.SubItemsParams{
  {Plan: "plan_CBb6IXqvTLXp3f",},
}
params := &stripe.SubParams{
  Customer: "cus_4fdAW5ftNQow1a",
  Items: items,
  TrialEnd: 1527490525,
  BillingCycleAnchor: 1528095325,
}
subscription, _ := sub.New(params)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.SetApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

var items = new List<StripeSubscriptionItemOption> {
    new StripeSubscriptionItemOption {PlanId = "plan_CBb6IXqvTLXp3f"}
};
var options = new StripeSubscriptionCreateOptions {
    Items = items,
    TrialEnd = 1527490525,
    BillingCycleAnchor = 1528095325,
};
var service = new StripeSubscriptionService();
StripeSubscription subscription = service.Create("cus_4fdAW5ftNQow1a", options);

Combining trials with metered plans

Applying trial periods to subscriptions with metered billing plans will work as expected. During the trial period, any usage accrued on the metered billing plan will not count towards the total charged to the customer at the end of the billing cycle.

Next steps

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