Setting Subscription Quantities

    Vary a subscription's cost by subscribing a customer to multiple quantities of a plan. If you need help after reading this, search our documentation or check out answers to common questions. You can even chat live with other developers in #stripe on freenode.

    By default, each subscription is to one instance of a plan, but Stripe allows you to subscribe a customer to multiple quantities of a single plan. For example, say you run a hosting company through which customers host sites at a cost of $9.99 per site per month. Most customers host a single site, while some host many. You could create plans for one site ($9.99), two sites ($19.98), and so forth, but a better approach is to subscribe customers to a quantity of the base $9.99 plan.

    Setting multiple quantities

    To set the quantity of a plan on a subscription, provide a quantity value when creating or updating the subscription:

    curl https://api.stripe.com/v1/subscriptions \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d customer=cus_4fdAW5ftNQow1a \
       -d plan=pro-monthly \
       -d quantity=5
    
    # 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"
    
    Stripe::Subscription.create(
      :customer => "cus_4fdAW5ftNQow1a",
      :plan => "pro-monthly",
      :quantity => 5,
    )
    
    # 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"
    
    stripe.Subscription.create(
      customer="cus_4fdAW5ftNQow1a",
      plan="pro-monthly",
      quantity=5,
    )
    
    // 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");
    
    \Stripe\Subscription::create(array(
      "customer" => "cus_4fdAW5ftNQow1a",
      "plan" => "pro-monthly",
      "quantity" => 5,
    ));
    
    // 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<String, Object>();
    params.put("customer", "cus_4fdAW5ftNQow1a");
    params.put("plan", "pro-monthly");
    params.put("quantity", 5);
    
    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");
    
    stripe.subscriptions.create({
      customer: "cus_4fdAW5ftNQow1a",
      plan: "pro-monthly",
      quantity: 5,
    }, function(err, subscription) {
      // asynchronously called
    });
    
    // 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.SubscriptionParams{
      Customer: "cus_4fdAW5ftNQow1a"
      Plan: "pro-monthly"
      Quantity: 5
    }
    subscription, err := sub.New(params)
    

    Multiple quantities of a plan are still billed using one invoice, and are prorated when the subscription changes, including when you change just the quantities involved.

    Creating dynamic billing amounts

    The quantity parameter provides another way to use subscriptions: creating a dynamic billing amount charged on a recurring basis. For example, say you have a subscription that has a base cost of $10 per month, and a $5 per-seat cost per month. One solution is to use quantities to represent the per-seat costs and add the base cost as an invoice item.

    A second solution is to subscribe the customer to multiple plans.

    A third solution is to create a base plan that is only $1 per month. This lets you use the quantity parameter to bill each user very flexibly. With a $10 base cost and three $5 seats, you could use a $1 per month plan, and set quantity=25 to achieve the desired total cost of $25 per month.

    The most important limitation for using quantities is that they must be set before an invoice is created. Quantities are useful for dynamically setting the billing amount when you know in advance how much to charge. Otherwise you want to use invoice items.

    Next steps

    Now that you understand how to use quantities, you may want to check out: