Tiered Pricing

    Learn how to use tiered pricing plans.

    Create plans using tiers when you need non-linear pricing as you adjust quantity or Usage. Tiered plans can be combined with other plans to create complex subscriptions with base fees and more.

    Tiered plans can be applied to a subscription just like licensed pricing plans.

    When a Plan is created using billing_scheme=per_unit, the amount behaves as a unit cost for the Plan. As quantity or Usage change, the amount of the Plan is simply multiplied by the quantity or Usage at the end of the period. Here is a simple example for a Plan with an amount of $5:

    Quantity/Usage at end of period Total for per unit pricing
    1 $5
    5 $25
    6 $30
    20 $100
    25 $125

    The next two sections demonstrate how to apply tiered pricing with volume and graduated modes, using the following tiering structure:

    Tier Amount (unit cost)
    1-5 (up_to=5) $5 (unit_amount=500)
    6-10 (up_to=10) $4 (unit_amount=400)
    10-15 (up_to=15) $3 (unit_amount=300)
    15-20 (up_to=20) $2 (unit_amount=200)
    20+ (up_to=inf) $1 (unit_amount=100)

    Volume

    When calculating the total for a plan with tiers_mode=volume, the quantity or Usage at the end of the period is used to select a tier. The entire quantity or Usage is multiplied by the appropriate unit cost.

    Quantity/Usage at end of period Total for volume tiered pricing
    1 $5
    5 $25
    6 $24
    20 $40
    25 $25

    As you can see, because the tier price is applied to the entire quantity or Usage, the total can actually go down when calculating the final cost.

    Graduated

    When calculating the total for a plan with tiers_mode=graduated, the quantity or Usage at each tier is multiplied by the usage that falls into that tier. Then, the total is summed. For example, the total cost for a usage of 6 is $29: $25 for the 5 quantity or Usage that fall into the 1 - 5 tier, plus $4 for the single quantity or Usage that falls into the 6 - 10 tier.

    Quantity/Usage at end of period Total for graduated tiered pricing
    1 $5
    5 $25
    6 $29
    20 $70
    25 $75

    Using Flat Fees

    In addition to specifying a unit cost per tier (unit_amount), you can also specify a flat fee (flat_amount) to be added to the invoice. This works for for both tiers_mode=volume and tiers_mode=graduated. For example, you can have flat fee that increases when certain usage thresholds are met:

    Tier Amount (unit cost) Flat fee
    1-5 (up_to=5) $5 (unit_amount=500) $10 (flat_amount=1000)
    6-10 (up_to=10) $4 (unit_amount=400) $20 (flat_amount=2000)
    10-15 (up_to=15) $3 (unit_amount=300) $30 (flat_amount=3000)
    15-20 (up_to=20) $2 (unit_amount=200) $40 (flat_amount=4000)
    20+ (up_to=inf) $1 (unit_amount=100) $50 (flat_amount=5000)

    In this example, if the quantity is 12 and the tiers_mode=volume, the total amount to be billed is 12 * $3 + $30 = $66. If the quantity is 12 and the tiers_mode=graduated, the total amount is 5 * $5 + $10 + 5 * $4 + $20 + 2 * $3 + $30 = $111. Note that a tier can have either a unit_amount or a flat_amount, or both, but at least one of the two is required to be set.

    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.