Subscriptions Quickstart

Learn how to set up basic recurring billing for your customers. If you need help after reading this, check out our answers to common questions or chat live with other developers in #stripe on freenode.

Billing your customers periodically is a common business model, and is easy to do with Stripe, requiring only three steps:

  1. Define a plan that sets how much should be billed and at what interval
  2. Create a customer in your Stripe account
  3. Subscribe the customer to the plan

After creating a plan once, you only need to execute the second and third steps for every subsequent customer.

The rest of this quickstart goes through these steps in detail, but you need to install one of our client libraries on your server to run the example code.

Step 1: Define a plan

Plans are objects representing a set cost, currency, and billing cycle. You may need to define just one plan or several hundred, depending upon the range of service levels or products you offer. For example, if you have two types of customers–one using the basic features of your application for free and another using the pro features for $30 per month, you would create Basic and Pro plans in your Stripe account.

This code creates the Basic plan via the API:

curl https://api.stripe.com/v1/plans \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d name="Basic Plan" \
   -d id=basic-monthly \
   -d interval=month \
   -d currency=usd \
   -d amount=0
# 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"

plan = Stripe::Plan.create(
  :name => "Basic Plan",
  :id => "basic-monthly",
  :interval => "month",
  :currency => "usd",
  :amount => 0,
)
# 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"

plan = stripe.Plan.create(
  name="Basic Plan",
  id="basic-monthly",
  interval="month",
  currency="usd",
  amount=0,
)
// 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");

$plan = \Stripe\Plan::create(array(
  "name" => "Basic Plan",
  "id" => "basic-monthly",
  "interval" => "month",
  "currency" => "usd",
  "amount" => 0,
));
// 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("name", "Basic Plan");
params.put("id", "basic-monthly");
params.put("interval", "month");
params.put("currency", "usd");
params.put("amount", 0);

Plan plan = Plan.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");

var plan = stripe.plans.create({
  name: "Basic Plan",
  id: "basic-monthly",
  interval: "month",
  currency: "usd",
  amount: 0,
}, function(err, plan) {
  // 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.PlanParams{
  Name: "Basic Plan",
  Id: "basic-monthly",
  Interval: "month",
  Currency: "usd",
  Amount: 0,
}
plan, err := plan.New(params)

Each plan requires a unique ID. You’ll provide this ID value in API requests when you subscribe a customer to the plan. The rest of this tutorial assumes you’ve created a Basic plan using either the Dashboard or the API.

Step 2: Create a customer

Customers as Stripe objects represent your actual customers and provide an easy way to process their payments. Typically, you’ll store some metadata on the customer object, too, like an email address.

You can create a customer with or without a stored payment method–such as a credit card or bank account (for ACH payments)–to allow for subsequent billing. As the Basic plan has no cost, you can subscribe a customer to it without a payment method.

As the Pro plan has an initial and monthly charge of $30, only customers with a stored payment method can be subscribed to it. You can securely collect a customer’s payment information via Checkout or Stripe.js.

This code creates a customer via the API, without a stored payment method:

curl https://api.stripe.com/v1/customers \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d email="jenny.rosen@example.com"
# 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"

customer = Stripe::Customer.create(
  :email => "jenny.rosen@example.com",
)
# 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"

customer = stripe.Customer.create(
  email="jenny.rosen@example.com",
)
// 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(
  "email" => "jenny.rosen@example.com",
));
// 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("email", "jenny.rosen@example.com");

Customer customer = Customer.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");

var customer = stripe.customers.create({
  email: "jenny.rosen@example.com",
}, 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.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

params := &stripe.CustomerParams{
  Email: "jenny.rosen@example.com",
}
customer, err := customer.New(params)

Stripe returns a new Customer object with all the relevant details:

{
  "id": "cus_4fdAW5ftNQow1a",
  "object": "customer",
  "account_balance": 0,
  "created": 1481352871,
  "currency": null,
  ...
  "livemode": false,
  "email": "jenny.rosen@example.com",
  ...
}

Once you create the customer, store the id value in your own database for later reference (presumably with the customer's email address). The above is just part of the Customer object; the complete object returned by the create customer call would also show this customer has neither a payment source nor a subscription.

Step 3: Subscribe the customer to the plan

Finally, create the subscription by associating the plan with the customer:

curl https://api.stripe.com/v1/subscriptions \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d customer=cus_4fdAW5ftNQow1a \
   -d plan=basic-monthly
# 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 => customer.id,
  :plan => "basic-monthly",
)
# 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=customer.id,
  plan="basic-monthly",
)
// 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" => $customer->id,
  "plan" => "basic-monthly",
));
// 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", customer.id);
params.put("plan", "basic-monthly");

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: customer.id,
  plan: "basic-monthly",
}, 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.SubscriptionParams{
  Customer: customer.id,
  Plan: "basic-monthly",
}
subscription, err := sub.New(params)

You now have a customer subscribed to a plan! Behind the scenes, Stripe creates an invoice for every billing cycle. The invoice outlines what the customer owes, reflects when they will be or were charged, and tracks the payment status. You can even add additional items to an invoice to factor in one-off charges like setup fees.

Since most subscription activity happens automatically from this point forward, you’ll want to establish webhooks to be notified of events as they occur.

Next steps

Congrats! You’ve created a subscription in Stripe! You may want to learn how to create subscriptions in more detail or move on to related subjects: