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

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

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