Using Trial Periods on Subscriptions

    Delay payments on active subscriptions using trial periods. If you need help after reading this, search our documentation or check out answers to common questions. You can even chat live with other developers in #stripe on freenode.

    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 plan=pro-monthly \
       -d trial_end=1498959949
    
    # 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.create(
      :customer => "cus_4fdAW5ftNQow1a",
      :plan => "pro-monthly",
      :trial_end => 1498959949,
    )
    
    # 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.create(
      customer="cus_4fdAW5ftNQow1a",
      plan="pro-monthly",
      trial_end=1498959949,
    )
    
    // 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::create(array(
      "customer" => "cus_4fdAW5ftNQow1a",
      "plan" => "pro-monthly",
      "trial_end" => 1498959949,
    ));
    
    // 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> params = new HashMap<String, Object>();
    params.put("customer", "cus_4fdAW5ftNQow1a");
    params.put("plan", "pro-monthly");
    params.put("trial_end", 1498959949);
    
    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");
    
    stripe.subscriptions.create({
      customer: "cus_4fdAW5ftNQow1a",
      plan: "pro-monthly",
      trial_end: 1498959949,
    }, function(err, subscription) {
      // asynchronously called
    });
    
    // 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{
      Customer: "cus_4fdAW5ftNQow1a",
      Plan: "pro-monthly",
      TrialEnd: 1498959949,
    }
    subscription, err := sub.New(params)
    

    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.

    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 activate a subscription without waiting for the trial period to end, make an update subscription API call, setting the trial_end value to now:

    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"
    
    subscription = Stripe::Subscription.retrieve("sub_49ty4767H20z6a")
    subscription.trial_end = "now"
    subscription.save
    
    # 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.retrieve("sub_49ty4767H20z6a")
    subscription.trial_end = "now"
    subscription.save()
    
    // 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::retrieve("sub_49ty4767H20z6a");
    $subscription->trial_end = "now";
    $subscription->save();
    
    // 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<String, Object>();
    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" },
      function(err, subscription) {
        // asynchronously called
      }
    );
    
    // 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, err := sub.Update("sub_49ty4767H20z6a", params)
    

    Next steps

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