Billing
Additional features
Tiered pricing

Tiered pricing

Learn how to use tiered pricing.

Use tiers when you need non-linear pricing as quantity or usage change. Tiered pricing can be combined with other prices to create complex subscriptions with base fees and more.

When a price is created using billing_scheme=per_unit, the amount behaves as the unit cost. This amount is multiplied by the quantity or usage at the end of the period to determine the total cost. This example uses an amount of $5:

Quantity/Usage at end of period Total cost
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 cost using 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 cost using 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 both tiers_mode=volume and tiers_mode=graduated. For example, you can have a 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.

Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.