Tiered

Tiered pricing (also called graduated pricing) sets a different rate for each band of quantity. As the quantity grows it crosses into the next band, and only the units inside each band are charged at that band's rate. The final price is the sum of every band.

Use it when you want bigger customers to pay less per unit, but only on the extra units, not retroactively on all of them.

Worked example

You price API calls in three bands:

Band	Rate per unit
1 to 50	$10.00
51 to 150	$8.00
151 and up	$6.00

A customer makes 100 calls. The first 50 fall in the first band, the next 50 in the second:

50 units x $10.00 = $500.00
50 units x  $8.00 = $400.00
total             = $900.00

The customer does not pay $8.00 for all 100 units. The first 50 stay at $10.00. That is the difference between tiered and volume pricing: tiered keeps each band at its own rate, volume reprices everything at the landing band.

Settings

Each band has three fields:

Field	What it does
Up to	The band's upper limit. Leave the last band's limit empty to mean "and up".
Unit amount	The price per unit inside this band.
From	The lower bound, shown for display. It follows from the previous band's upper limit.

Edge cases

• The bands are cumulative. "Up to 150" means the band ends at a running total of 150 units, not 150 more units on top of the previous band.
• The last band must be open. Leave its upper limit empty so any quantity is priced.
• Free allowances are a per unit feature. Tiered pricing does not subtract an included quantity. If you want a free allowance, use per unit pricing, or make the first band's rate zero.

In the API

{
  "pricing_model": "tiered",
  "pricing_config": {
    "tiers": [
      { "tier_from": 0,   "tier_to": 50,   "unit_amount": 1000 },
      { "tier_from": 51,  "tier_to": 150,  "unit_amount": 800 },
      { "tier_from": 151, "tier_to": null, "unit_amount": 600 }
    ]
  },
  "currency": "USD"
}