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:

    Questions?

    We're always happy to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

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