# 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.

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 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.