Billing
Additional features
Tiered pricing

Tiered pricing

Learn how to change invoice amounts based on how much your customers buy.

Use tiers if you need non-linear pricing when quantity or usage changes. Tiered pricing can also be combined with base fees or other pricing models to create complex subscriptions.

When you create a price with billing_scheme=per_unit, the unit_amount is the same regardless of how many units a customer buys. This amount is multiplied by the quantity to determine the total cost. For example, a unit_amount of $5 creates this billing structure:

Quantity/Usage at end of periodTotal cost
1$5
5$25
6$30
20$100
25$125

When you create a price with billing_scheme=tiered, the unit cost varies depending on how many units your customer buys. Here’s an example tiers structure:

TierAmount (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)

Multiplication is performed at the start of the billing period for Price objects with recurring.usage_type = licensed, and at the end of the billing period for Price objects with recurring.usage_type = metered.

With tiered billing, you also set the tiers_mode to one of volume or graduated, and create a tiers array to represent the tiers structure. See also the volume-based and graduated pricing examples.

Volume

With tiers_mode=volume, the entire quantity is multiplied by the unit cost of the tier.

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

Because the tier price is applied to the entire quantity or usage, the total can decrease when calculating the final cost.

Graduated

With tiers_mode=graduated, the quantity is multiplied by the amount that falls into that tier. Then, the total is summed. For example, the total cost for an amount of 6 is $29: $25 for the 5 quantity that falls into the 1 - 5 tier, plus $4 for the single quantity that falls into the 6 - 10 tier.

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

Adding Flat Fees

In addition to specifying a unit cost per tier (unit_amount), you can also specify a flat fee (flat_amount) to add 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:

TierAmount (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 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 it must have at least one of the two.