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:

    1. Manually—for one-off invoices.
    2. 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:

    1. Create a customer in your Stripe account.
    2. Create a one-off invoice for your customer from your Stripe Dashboard.

    To automatically invoice and bill your customer periodically, follow these three steps:

    1. Define a service product and pricing 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.

    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": 1571534170,
      "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": 1571534170,
      "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 {Plan = "plan_CBXbz9i7AIOTzr"}
    };
    var options = new SubscriptionCreateOptions {
        Customer = "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:

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page