Billing Quickstart
Learn how to set up basic recurring billing for your customers.
Stripe Billing is a recurring billing engine integrated within the Stripe platform. Its job is to generate invoices. The Billing engine then automatically works towards collecting payments on those invoices.
Invoices are created in one of two ways:
- Manually—for one-off invoices
- Automatically—on a recurring basis for subscriptions.
How to bill
Billing your customers is easy with Stripe. You can invoice a customer when needed, or invoice on a recurring basis using subscriptions.
To create a one-off invoice:
- Create a customer in your Stripe account.
- Create a one-off invoice for your customer from your Stripe Dashboard.
To automatically invoice and bill your customer periodically, follow these three steps:
- Define a service product and pricing plan that sets how much should be billed and at what interval.
- Create a customer in your Stripe account.
- Subscribe the customer to the plan.
The rest of this quickstart goes through the subscription steps in detail. To run the example code, you must install one of our client libraries on your server.
Step 1: Define a service product and pricing plan
Before you can create subscriptions, you must first create the product that represents the service you intend to offer to your customers. Use the type
parameter to specify that the product is a service-type product and thus intended for subscriptions.
The following code demonstrates how to create a service-type product:
curl https://api.stripe.com/v1/products \
-u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
-d name="My SaaS Platform" \
-d type=service
# 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_4eC39HqLyjWDarjtT1zdp7dc'
product = Stripe::Product.create({
name: 'My SaaS Platform',
type: 'service',
})
# 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_4eC39HqLyjWDarjtT1zdp7dc'
product = stripe.Product.create(
name='My SaaS Platform',
type='service',
)
// 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_4eC39HqLyjWDarjtT1zdp7dc');
$product = \Stripe\Product::create([
'name' => 'My SaaS Platform',
'type' => 'service',
]);
// 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_4eC39HqLyjWDarjtT1zdp7dc";
Map<String, Object> params = new HashMap<String, Object>();
params.put("name", "My SaaS Platform");
params.put("type", "service");
Product.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
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
(async () => {
const product = await stripe.products.create({
name: 'My SaaS Platform',
type: 'service',
});
})();
// 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_4eC39HqLyjWDarjtT1zdp7dc"
params := &stripe.ProductParams{
Name: stripe.String("My SaaS Platform"),
Type: stripe.String(string(stripe.ProductTypeService)),
}
prod, _ := product.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.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
var options = new ProductCreateOptions {
Name = "My SaaS Platform",
Type = "service",
};
var service = new ProductService();
Product product = service.Create(options);
When creating a product through the API, the response includes an ID, which you can use to attach plans to the product:
{
"id": "prod_CbvTFuXWh7BPJH",
"object": "product",
...
"name": "My SaaS Platform",
"type": "service",
}
A plan is an object that represents per-item cost, currency, and billing cycle. Every plan is attached to a product. You may need to define just one plan or several hundred, depending on how many variations you offer. For example, if you accept different currencies in various regions, you might want to create separate USD and JPY plans attached to the same product.
To attach a plan to an existing product, pass the ID of the desired product as the value of the product
parameter. This code creates a SaaS Platform USD plan via the API and attaches it to a product:
curl https://api.stripe.com/v1/plans \
-u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
-d product=prod_CbvTFuXWh7BPJH \
-d nickname="SaaS Platform USD" \
-d interval=month \
-d currency=usd \
-d amount=10000
# 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_4eC39HqLyjWDarjtT1zdp7dc'
plan = Stripe::Plan.create({
product: 'prod_CbvTFuXWh7BPJH',
nickname: 'SaaS Platform USD',
interval: 'month',
currency: 'usd',
amount: 10000,
})
# 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_4eC39HqLyjWDarjtT1zdp7dc'
plan = stripe.Plan.create(
product='prod_CbvTFuXWh7BPJH',
nickname='SaaS Platform USD',
interval='month',
currency='usd',
amount=10000,
)
// 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_4eC39HqLyjWDarjtT1zdp7dc');
$plan = \Stripe\Plan::create([
'product' => 'prod_CbvTFuXWh7BPJH',
'nickname' => 'SaaS Platform USD',
'interval' => 'month',
'currency' => 'usd',
'amount' => 10000,
]);
// 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_4eC39HqLyjWDarjtT1zdp7dc";
Map<String, Object> params = new HashMap<String, Object>();
params.put("product", "prod_CbvTFuXWh7BPJH");
params.put("nickname", "SaaS Platform USD");
params.put("interval", "month");
params.put("currency", "usd");
params.put("amount", 10000);
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
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
(async () => {
const plan = await stripe.plans.create({
product: 'prod_CbvTFuXWh7BPJH',
nickname: 'SaaS Platform USD',
currency: 'usd',
interval: 'month',
amount: 10000,
});
})();
// 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_4eC39HqLyjWDarjtT1zdp7dc"
params := &stripe.PlanParams{
ProductID: stripe.String("prod_CbvTFuXWh7BPJH"),
Nickname: stripe.String("SaaS Platform USD"),
Interval: stripe.String(string(stripe.PlanIntervalMonth)),
Currency: stripe.String(string(stripe.CurrencyUSD)),
Amount: stripe.Int64(10000),
}
p, err := 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.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
var options = new PlanCreateOptions {
Product = "prod_CbvTFuXWh7BPJH",
Nickname = "SaaS Platform USD",
Interval = "month",
Currency = "usd",
Amount = 10000,
};
var service = new PlanService();
Plan plan = service.Create(options);
Stripe returns a new plan object with all of the relevant details:
{
"id": "plan_CbvZlrtet27kcB",
"object": "plan",
"amount": 10000,
"billing_scheme": "per_unit",
"created": 1562716465,
"currency": "usd",
"interval": "month",
"interval_count": 1,
"livemode": false,
"metadata": {},
"nickname": "SaaS Platform USD",
"product": "prod_CbvTFuXWh7BPJH",
"tiers": null,
"tiers_mode": null,
"transform_usage": null,
"trial_period_days": null,
"usage_type": "licensed"
}
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 SaaS Platform USD plan using either the Dashboard or the API.
Step 2: Create a customer
Customers are Stripe objects that represent your actual customers, providing 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 SaaS Platform USD plan has an initial and monthly charge of $100, only customers with a stored payment method can be subscribed to it. You can securely collect a customer’s payment information via our recommend payments integrations.
This code creates a customer via the API and provides a source to serve as the stored payment method:
curl https://api.stripe.com/v1/customers \
-u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
-d email="jenny.rosen@example.com" \
-d source=src_18eYalAHEMiOZZp1l9ZTjSU0
# 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_4eC39HqLyjWDarjtT1zdp7dc'
customer = Stripe::Customer.create({
email: 'jenny.rosen@example.com',
source: 'src_18eYalAHEMiOZZp1l9ZTjSU0',
})
# 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_4eC39HqLyjWDarjtT1zdp7dc'
customer = stripe.Customer.create(
email='jenny.rosen@example.com',
source='src_18eYalAHEMiOZZp1l9ZTjSU0',
)
// 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_4eC39HqLyjWDarjtT1zdp7dc');
$customer = \Stripe\Customer::create([
'email' => 'jenny.rosen@example.com',
'source' => 'src_18eYalAHEMiOZZp1l9ZTjSU0',
]);
// 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_4eC39HqLyjWDarjtT1zdp7dc";
Map<String, Object> params = new HashMap<>();
params.put("email", "jenny.rosen@example.com");
params.put("source", "src_18eYalAHEMiOZZp1l9ZTjSU0");
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
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
(async () => {
const customer = await stripe.customers.create({
email: 'jenny.rosen@example.com',
source: 'src_18eYalAHEMiOZZp1l9ZTjSU0',
});
})();
// 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_4eC39HqLyjWDarjtT1zdp7dc"
params := &stripe.CustomerParams{
Email: stripe.String("jenny.rosen@example.com"),
}
params.SetSource("src_18eYalAHEMiOZZp1l9ZTjSU0")
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.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
var options = new CustomerCreateOptions {
Email = "jenny.rosen@example.com",
Source = "src_18eYalAHEMiOZZp1l9ZTjSU0",
};
var service = new CustomerService();
Customer customer = service.Create(options);
Stripe returns a new Customer
object with all the relevant details:
{
"id": "cus_4fdAW5ftNQow1a",
"object": "customer",
"account_balance": 0,
"created": 1562716465,
"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 does not have 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_4eC39HqLyjWDarjtT1zdp7dc: \
-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_4eC39HqLyjWDarjtT1zdp7dc'
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_4eC39HqLyjWDarjtT1zdp7dc'
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_4eC39HqLyjWDarjtT1zdp7dc');
$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_4eC39HqLyjWDarjtT1zdp7dc";
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
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
(async () => {
const subscription = await 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_4eC39HqLyjWDarjtT1zdp7dc"
items := []*stripe.SubscriptionItemsParams{
{
Plan: stripe.String("plan_CBXbz9i7AIOTzr"),
},
}
params := &stripe.SubscriptionParams{
Customer: stripe.String("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.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";
var items = new List<SubscriptionItemOption> {
new SubscriptionItemOption {PlanId = "plan_CBXbz9i7AIOTzr"}
};
var options = new SubscriptionCreateOptions {
CustomerId = "cus_4fdAW5ftNQow1a",
Items = items,
};
var service = new SubscriptionService();
Subscription subscription = service.Create(options);
You now have a customer subscribed to a plan. If the first payment succeeds, the subscription is in status active
. Otherwise, the status is incomplete
and the subscription expires in 23 hours unless payment on the latest_invoice is collected. Behind the scenes, Stripe creates further invoices 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 (see the invoice workflow and lifecycle docs for more detail), you’ll want to establish webhooks to be notified of events as they occur.
Next steps
Congratulations! You’ve created a subscription in Stripe. Next, you might want to learn how to create subscriptions in more detail, or move on to related subjects: