Setting Subscription Quantities

Vary a subscription’s cost by subscribing a customer to multiple quantities of a plan.

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.

There are two kinds of usage-based billing for subscriptions: metered billing, and per-seat licensing. You can enable these billing models by setting the value of the usage_type attribute when creating a plan. You may only specify a quantity when subscribing a user to a plan configured with licensed as the value of usage_type. If you would like to have granular billing for usage that fluctuates within a billing interval, consider using metered billing instead of quantities.

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 items[0][plan]=plan_CBb6IXqvTLXp3f \
   -d items[0][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"

subscription = Stripe::Subscription.create({
    customer: 'cus_4fdAW5ftNQow1a',
    items: [
        {
            plan: 'plan_CBb6IXqvTLXp3f',
            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"

subscription = stripe.Subscription.create(
  customer='cus_4fdAW5ftNQow1a',
  items=[
    {
      'plan': 'plan_CBb6IXqvTLXp3f',
      '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");

$subscription = \Stripe\Subscription::create([
    'customer' => 'cus_4fdAW5ftNQow1a',
    'items' => [
        [
            'plan' => 'plan_CBb6IXqvTLXp3f',
            '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> item = new HashMap<>();
item.put("plan", "plan_CBb6IXqvTLXp3f");
item.put("quantity", 5);
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
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

const subscription = stripe.subscriptions.create({
  customer: 'cus_4fdAW5ftNQow1a',
  items: [
    {
      plan: 'plan_CBb6IXqvTLXp3f',
      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.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

items := []*stripe.SubItemsParams{
  {
    Plan: "plan_CBb6IXqvTLXp3f",
    Quantity: 5,
  },
}
params := &stripe.SubParams{
  Customer: "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.SetApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

var items = new List<StripeSubscriptionItemOption> {
  new StripeSubscriptionItemOption {
      PlanId = "plan_CBb6IXqvTLXp3f",
      Quantity = 5,
  }
};
var options = new StripeSubscriptionCreateOptions {
    Items = items,
};
var service = new StripeSubscriptionService();
StripeSubscription subscription = service.Create("cus_4fdAW5ftNQow1a", options);

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.

Charging different amounts based on quantity

In some cases, you may want to adjust the cost per seat based on the number of seats in a subscription. For example, you could offer volume licensing discounts for subscriptions that exceed certain quantity thresholds. You can use tiers to adjust per-seat pricing in that manner.

Next steps

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