Subscriptions Quickstart

    Learn how to set up basic recurring billing for your customers.

    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

    A plan is an object that represents a set cost, currency, and billing cycle. Plans are attached to a product, an object that describes the general offering that you make available to customers. You may need to define just one plan or several hundred, depending upon the range of service levels and product variations 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 attached to a product that represents your application.

    This code creates the Basic plan via the API:

    curl https://api.stripe.com/v1/plans \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d product[name]="Basic Product" \
       -d currency=usd \
       -d interval=month \
       -d name="Basic Monthly" \
       -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({
      product: {
        name: 'Basic Product',
      },
      nickname: 'Basic Monthly',
      currency: 'usd',
      interval: 'month',
      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(
      product={'name': 'Basic Product'},
      nickname='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([
      'product' => {'name' => 'Basic Product'},
      'nickname' => '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> productParams = new HashMap<String, Object>();
    productParams.put("name", "Basic Product");
    
    Map<String, Object> params = new HashMap<String, Object>();
    params.put("product", productParams);
    params.put("nickname", "Basic Monthly");
    params.put("interval", "month");
    params.put("currency", "usd");
    params.put("interval", "month");
    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");
    
    const plan = stripe.plans.create({
      product: {name: "Basic Product"},
      currency: 'usd',
      interval: 'month',
      nickname: 'Basic Monthly',
      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.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    params := &stripe.PlanParams{
      Product: &stripe.ProductParams{
        Name: "Basic Product",
      },
      Nickname: "Basic Monthly",
      Interval: "month",
      Currency: "usd",
      Interval: "month",
      AmountZero: true,
    }
    basic, _ := plan.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 options = new StripePlanCreateOptions {
        Currency = "usd",
        Interval = "month",
        Nickname = "Basic Plan",
        Amount = 0,
        Product = new StripeProductCreateOptions
        {
          Name = "Basic Product"
        }
    };
    var service = new StripePlanService();
    StripePlan plan = service.Create(options);
    

    When you create a plan, you can either attach it to an existing product or create a new product. The example above demonstrates how to create a product and plan simultaneously, by supplying the product name during plan creation. If you wish to attach a plan to an existing product, provide the desired product ID instead of parameters that describe a new product.

    Plans have a unique ID that is generated automatically upon plan creation. Provide this ID in API requests when subscribing customers 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 are Stripe objects that represent your actual customers and provide an easy way to process their payments. Typically, you might also store metadata, such as an email address, on the customer object.

    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 Elements.

    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([
        '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<>();
    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");
    
    const customer = stripe.customers.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.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    params := &stripe.CustomerParams{
      Email: "jenny.rosen@example.com",
    }
    cus, _ := customer.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 options = new StripeCustomerCreateOptions {
        Email = "jenny.rosen@example.com",
    };
    var service = new StripeCustomerService();
    StripeCustomer customer = service.Create(options);
    

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

    {
      "id": "cus_4fdAW5ftNQow1a",
      "object": "customer",
      "account_balance": 0,
      "created": 1518923888,
      "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 items[0][plan]=plan_CBXbz9i7AIOTzr
    
    # 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_CBXbz9i7AIOTzr'}],
    })
    
    # 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_CBXbz9i7AIOTzr'}],
    )
    
    // 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_CBXbz9i7AIOTzr']],
    ]);
    
    // 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_CBXbz9i7AIOTzr");
    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);
    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_CBXbz9i7AIOTzr'}],
    });
    
    // 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_CBXbz9i7AIOTzr",},
    }
    params := &stripe.SubParams{
      Customer: "cus_4fdAW5ftNQow1a",
      Items: items,
    }
    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_CBXbz9i7AIOTzr"}
    };
    var options = new StripeSubscriptionCreateOptions {
        Items = items,
    };
    var service = new StripeSubscriptionService();
    StripeSubscription subscription = service.Create("cus_4fdAW5ftNQow1a", options);
    

    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: