# subscriptions.usage-tiered

Tiered pricing for metered usage, in the two modes Stripe calls `graduated`
and `volume`, with Stripe's `up_to` and `flat_amount` semantics. With tiers of
1-5 at 7.00, 6-10 at 6.50 and 11+ at 6.00 (Stripe's own worked example):

- **graduated**: each unit is priced in the tier it falls in. 6 units are
  5 x 7.00 + 1 x 6.50 = 41.50; 20 units are 127.50.
- **volume**: every unit is priced at the tier the whole quantity falls in.
  6 units are 6 x 6.50 = 39.00, which is less than 5 units at 35.00 would
  suggest by extrapolation: volume totals can fall as usage rises across a
  boundary, and that is correct.

A tier's `upTo` is the last unit in it, inclusive, so usage of exactly 10
against tiers ending at 5 and 10 is wholly inside the first two tiers and
does not reach the third, flat fee included. The last tier may be open-ended
(`upTo` null); if it is not, usage beyond it is an error rather than being
silently priced at the last rate.

Flat fees. In graduated mode a tier's flat fee is charged once when usage
reaches the tier; in volume mode only the flat fee of the tier the quantity
falls in is charged. The first tier is always reached: usage of 0 still
charges the first tier's flat fee, in both modes, which is what Stripe does
("Stripe always bills the first flat rate tier when quantity=0"). To charge
nothing for no usage, make the first tier `upTo` 1 with a unit price instead
of a flat fee.

The result lists one line per tier that was charged, in tier order, with the
units priced in it, so an invoice can show the breakdown; `total` is their
sum. Everything is exact integer arithmetic in minor units - no rounding
happens anywhere. A per-unit price smaller than one minor unit (0.1p per API
call) cannot be written as Money; meter such usage in packages (per 1,000
calls) instead.

Errors: no tiers, a negative quantity, `upTo` values that are not positive and
strictly increasing, an open-ended tier before the last, usage beyond a closed
last tier, and prices in more than one currency.

Source: Stripe, "Set up tiered pricing",
https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing (the
vectors reproduce its volume, graduated and flat-rate examples).