Subscription Billing

Stripe makes recurring and subscription-based billing easy. This is a guide to some common use-cases. If you need help, check out our answers to common questions or chat live with our developers in #stripe on freenode.

Creating a plan

To get started, you'll need to set up a few plans in your dashboard or via the API. The first things you'll define are the price for your plan and the billing frequency. For example, if you have two groups of customers — one group who are using basic features of your application for $10 per month and another group who are using pro features for $30 per month — you can create a Basic plan and a Pro plan in your account.

Each plan has an unique id, which could be Basic and Pro in our example. This value is what you'll provide in API requests when you actually subscribe a customer to one of your plans.

Subscribing a customer to a plan

Subscriptions must be attached to customers in our API. Often you'll want to create a new customer with Stripe at the same time that you sign them up for a subscription. Our API lets you do this easily by allowing you to provide a plan in the same call to create a customer.

If you also provide a credit card, Stripe will store the credit card and ensure it can be charged before ever returning a response. Here's an example of creating a customer with a subscription and valid credit card in one request:

curl -i https://api.stripe.com/v1/customers
 -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
 -d plan=Basic
 -d description=new_paying_customer
 -d card[number]=4242424242424242
 -d card[exp_month]=01
 -d card[exp_year]=2012

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

{
  "object": "customer",
  "description": "new_paying_customer",
  "livemode": false,
  "created": 1305974416,
  "active_card": {
    "type": "Visa",
    "object": "card",
    "country": "US",
    "exp_month": 5,
    "last4": "4242",
    "id": "cc_f2jWdtB2GK",
    "exp_year": 2012
  },
  "subscription": {
    "current_period_end": 1306060846,
    "status": "trialing",
    "plan": {
      "interval": "month",
      "amount": 1000,
      "trial_period_days": 0,
      "object": "plan",
      "id": "Basic"
    },
    "current_period_start": 1305974416,
    "start": 1305974416,
    "object": "subscription",
    "trial_start": 1305974416,
    "trial_end": 1306060846,
    "customer": "O8ygDbcWW9aswmxctU9z",
  },
  "id": "O8ygDbcWW9aswmxctU9z"
}

This customer will be charged immediately for the first month of their subscription (often called pre-billing). They will be billed $10 every month until the subscription is canceled.

If the credit card had not been valid, an error would have been returned instead of a customer object. This makes it easy to ensure that Stripe will be able to charge the customer you store in your database.

Trial Periods

Another benefit you can offer subscription customers is free trial periods. When you create plans, one of the options you can set is how long the trial period will last. If you do choose to offer a trial period, the customers you sign up won't be charged for the first time until after the trial period has ended.

Changing a customer's subscription

Customers will often want to change to a new plan, e.g. by upgrading to the Pro plan in our examples. Stripe's API provides a simple mechanism for switching the customer's plan and automatically calculating the details like pro-rating for you.

curl -i https://api.stripe.com/v1/customers/O8ygDbcWW9aswmxctU9z/subscription
 -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
 -d plan=Pro

To give you a concrete example of what this might look like, let's say a customer signs up on April 1 for the Basic plan at $10 a month. Half way through April, the customer decides to switch to the Pro plan for $20 a month. She'll be charged $10 on April 1, the day she signed up, and then $25 on May 1: $20 for May 1 to June 1, minus $5 for the unused portion of the Basic plan, plus $10 for the 1/2 month on the more expensive Pro plan.

You can disable pro-rating if you like by passing an additional prorate option to the API request:

curl -i https://api.stripe.com/v1/customers/O8ygDbcWW9aswmxctU9z/subscription
 -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
 -d plan=Pro
 -d prorate=false

In this case, the customer will be charged $10 for the Basic plan during the month of April, and then $20 for the Pro plan during the month of May. It's up to you to determine how you handle this in your application or website, by either providing the new level of service immediately or waiting until the beginning of the next billing cycle. Usually it will be easier to just use our pro-rating feature and then make your service changes right away.

Canceling a customer's subscription

Sadly, customers sometimes want to cancel their subscriptions. Again this is done with a simple request to Stripe's API:

curl -i https://api.stripe.com/v1/customers/O8ygDbcWW9aswmxctU9z/subscription
 -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
 -X DELETE

When you cancel the subscription, the customer's card will not be charged again, but no money will be refunded either. If you'd like to issue a refund, you can do so through Stripe's dashboard or via the API.

If you'd like to keep the subscription active through the end of the current billing period, you can set the at_period_end parameter to true. In this case, the customer's subscription will simply be canceled at the end of the billing cycle and there won't be another charge to the card.

Coupons and discounts

If you want to provide discounts to certain customers, you can create coupon codes in Stripe's dashboard. Coupons have a discount percentage and a duration, so you could create coupons like a 10% lifetime discount, or a one month 50% discount, etc. Coupons can also have expiration dates attached, after which they can't be used. Here's an example of adding a discount to a user's subscription. In this case, we've already created a coupon called 50OFF1MONTH:

curl -i https://api.stripe.com/v1/customers/O8ygDbcWW9aswmxctU9z
 -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
 -d coupon=50OFF1MONTH

The customer's next bill will be discounted by 50%. You can also add a coupon at the same time you create the customer or subscription, in which case it will apply right away to the first bill.

Metered billing and one-time charges

When you have a customer on a subscription, you might sometimes need to add additional fees to their monthly bill. Examples might be customers who have used more capacity than their plan allows or initial setup fees for new subscribers. Both of these examples are easy to do with Stripe's API.

We call these non-recurring charges Invoice Items. To add a new invoice item to a customer's next bill, you make an API request like this:

curl -i https://api.stripe.com/v1/invoiceitems
 -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
 -d customer=O8ygDbcWW9aswmxctU9z
 -d amount=1000
 -d currency=usd
 -d "description=One-time setup fee"

Stripe will return an InvoiceItem object:

{
  "date": 1305974416,
  "description": "One-time setup fee",
  "currency": "usd",
  "amount": 1000,
  "object": "invoiceitem",
  "id": "ii_EOsoCIs2mE"
}

At the end of the upcoming billing period, this customer will be charged for her normal subscription amount plus the additional $10 setup fee. Invoice Items can be accessed, changed, or deleted at any point between when they are created and when they are actually charged to your customer.

Per-user pricing

With Stripe, you can also do per-seat pricing. To make use of this, just be sure to specify the quantity parameter when creating or updating the subscription for a customer. Using the example above, if you have per-user pricing and want to create a customer who will be getting 5 licenses to your service, you can make the following call:

curl -i https://api.stripe.com/v1/customers
 -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
 -d plan=Basic
 -d quantity=5
 -d description=new_paying_customer
 -d card[number]=4242424242424242
 -d card[exp_month]=01
 -d card[exp_year]=2012

Failed payments

Stripe makes handling failed payments easy. Stripe can automatically retry a recurring payment after it fails, and can automatically cancel the customer's subscription if it repeatedly fails. How long to wait, and how many times to retry, can be easily set in your account settings.

Invoice Timing

An invoice is created at the end of the subscription's billing cycle. Once created, Stripe will automatically attempt to pay the invoice using the card associated with your customer. If you have configured webhook URLs, Stripe will wait until one hour after all your URLs have successfully received a webhook (or, after the last webhook exhausts all attempts to retry).

More information

There are many more features in our API, like seeing past invoices that have been sent to a customer, previewing what the next invoice will look like, and our webhooks that notify you when interesting things happen, like failed payments and ending trial periods.

For the full set of available API methods, read through our API Documentation.