Creating Your First Subscription

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 use case, and it’s easy to do with Stripe, requiring only two steps:

  1. Create a plan that defines how much should be billed and at what interval
  2. Associate a plan with a customer to create a subscription

(After creating a plan once, you simply execute the second step for every subsequent customer.)

Before getting started, you’ll want to install one of our client libraries on your server, which is where you’ll run this tutorial’s code. You’ll need to also collect your customer’s credit card info. If you haven’t set up that functionality, look at our Checkout and custom form tutorials before reading on.

Step 1: Create a plan

Stripe’s subscription billing has two main primitives: plans and customers. Plans are objects representing a set cost and billing cycle. You may define just one plan or several hundred, covering the diversity of service levels you offer. For example, if you have two groups of customers–one using the basic features of your application for $10 per month and another using the pro features for $30 per month–you can create a Basic plan and a Pro plan in Stripe.

There are two ways to create plans:

The creation of a single plan via the API uses code like:

We’ve placed a random test API key in the code. Replace it with your actual API key to test this code through your Stripe account.

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

As a reminder, the plan itself only needs to be created once. It’s the association of the plan with a customer that creates a subscription.

Step 2: Subscribing a customer to a plan

Customers are the other main component of subscriptions. In a broad sense, a Customer object is just a generic way to associate your own users with your Stripe account. Typically, you’ll want to associate some metadata, like an email address, with a customer. Customer objects can also have a stored payment method, such as a credit card, that allows for subsequent billing.

You can create customers via the Dashboard, but as you’ll likely create them as part of the workflow at your site, it makes more sense to use the API. Below is a self-contained example that creates a customer and associates that customer with a plan in a single request. Also notice that a credit card is being attached to the customer. The card is represented by a token, collected from a payment form.

If the credit card is valid, Stripe will return a new Customer object with all the relevant details:

  "object": "customer",
  "created": 1409190039,
  "id": "cus_4fdAW5ftNQow1a",
  "livemode": false,
  "email": "",
  "subscriptions": {
    "object": "list",
    "total_count": 1,
    "has_more": false,
    "url": "/v1/customers/cus_4fdAW5ftNQow1a/subscriptions",
    "data": [
        "id": "sub_4fdAS9IlSOFfiv",
        "plan": {
          "interval": "month",
          "name": "Amazing Gold Plan",
          "created": 1409178429,
          "amount": 2000,
          "currency": "usd",
          "id": "gold",
          "object": "plan",
          "livemode": false,
          "interval_count": 1,
          "trial_period_days": null,
          "metadata": {},
          "statement_descriptor": null

Once you create a customer, you should store its id in your own database for later reference. This customer will be charged immediately for the first month of their subscription (often called pre-billing). They will continue to be billed $20 every month–the plan’s cost and interval–until the subscription is canceled.

If the credit card had not been valid, an error would have been returned instead of a Customer object.

Behind the scenes, Stripe creates an Invoice object for every billing cycle. The invoice reflects what your customer will be charged, when, and 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 setup webhooks to be notified of events as they occur.

Next up

Congrats! You’ve gone through the basics of creating a subscription in Stripe. Some things you might want to read next: