Trials

Subscriptions can begin with a free trial period in one of two ways:

Defining a trial in the plan itself
Setting a trial period when subscribing the customer to a plan by passing a trial_end timestamp

To do the latter, set a trial_end value (Unix timestamp in seconds) when creating the customer.

# 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::Customer.create(
  :source => token, # obtained from Stripe.js
  :plan => "basic_monthly",
  :email => "[email protected]"
  :trial_end => 1393407413
)

# 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.Customer.create(
  source=token, # obtained from Stripe.js
  plan="basic_monthly",
  email="[email protected]",
  trial_end=1393407413
)

// 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");

$customer = \Stripe\Customer::create(array(
  "source" => $token, // obtained from Stripe.js
  "plan" => "basic_monthly",
  "email" => "[email protected]",
  "trial_end" => 1393407413
));

// 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.customers.create({
  source: token, // obtained with Stripe.js
  plan: "basic_monthly",
  email: "[email protected]",
  trial_end: 1393407413
}, function(err, customer) {
  // 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.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Map<String, Object> customerParams = new HashMap<String, Object>();
customerParams.put("source", token); // obtained with Stripe.js
customerParams.put("plan", "basic_monthly");
customerParams.put("email", "[email protected]");
customerParams.put("trial_end", 1393407413);

Customer customer = Customer.create(customerParams);

When you define a plan with a trial period, every new customer subscribed to that plan will automatically receive that free trial period. The number of trial days a customer has used is tracked on a per-subscription basis. We will deduct the number of trial days previously consumed by a customer from the plan’s trial_period_days and use the remaining days, if any, for the trial. If you’d like to change the length of that trial period, you can use the code above to override it. Providing the value “now” for trial_end will enroll the customer to a subscription without a trial period.

Three days before the trial period is up, a customer.subscription.trial_will_end event will be sent to your webhook endpoint. If you’d like, you can use it as a trigger to email your customer that billing for the plan is about to begin.

Once the trial period is up, Stripe will generate an invoice and send out an invoice.created event notification. Approximately an hour later, Stripe will attempt to charge that invoice. Assuming that the payment attempt succeeded, you’ll receive notifications of the following events:

charge.succeeded
invoice.payment_succeeded
customer.subscription.updated (reflecting an update from a trial to an active subscription)

To make a subscription active without waiting for the trial period to end, you can use the update subscription API call, setting the trial_end value to “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
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.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

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

Map<String, Object> subscriptionParams = new HashMap<String, Object>();
subscriptionParams.put("trial_end", "now");

subscription.update(subscriptionParams);

Next up

Subscription Object API