Tiered pricing API
Price of a quantity under graduated or volume tiers, with optional flat fees, exactly as Stripe bills tiered prices.
POST https://api.curatedapi.com/v1/calc/billing/tiered-price
- Version 1
- MCP tool
calc_billing_tiered_price - Try it in the browser
Prices a quantity (seats, API calls, gigabytes) on a tiered price list. With graduated tiers, each unit is charged at the price of the tier it falls in, so 12 units on tiers of 5 are charged 5 at the first price, 5 at the second and 2 at the third. With volume tiers, every unit is charged at the price of the tier the whole quantity lands in. A tier can also have a flat fee: graduated pricing charges the flat fee of every tier it reaches, volume pricing only that of the tier it lands in. The tiers table shows how the total is made up.
Formula
graduated: Σ over tiers reached (min(q, up_to_k) − up_to_(k−1)) × price_k + fee_k; volume: q × price_k + fee_k for the first tier with q ≤ up_to_k
- Tier limits are inclusive, as in Stripe: with tier_up_to [5, 10], 5 units are in the first tier and 6 units reach the second.
- A quantity of 0 is in the first tier, so its flat fee is charged, as Stripe does. To charge nothing for no usage, give the first tier a limit of 1, a unit price equal to the flat fee and no flat fee.
- For stairstep pricing (one fixed price per band), use volume pricing with unit prices of 0 and the band prices as flat fees.
- The total is the exact price rounded once. Each tier's amount is rounded on its own for the table; if those rounded amounts do not add up to the total, a TIER_AMOUNTS_ROUNDED warning gives both.
- Amounts are rounded to the cent (2 decimals) half up by default, the usual commercial rule and the one Stripe Tax uses. Set options.decimals for currencies with other minor units (0 for JPY, 3 for KWD) and options.rounding for another rule.
Inputs
Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).
| Input | Type | Description |
|---|---|---|
quantity required |
decimal (string) | Number of units to price (whole or decimal, for metered usage). Allowed: >= 0 and <= 1000000000000000. |
pricing_model required |
graduated | volume | How the tiers apply. Options: graduated: each tier's units at that tier's price, summed (Stripe tiers_mode=graduated); volume: all units at the price of the tier the quantity lands in (Stripe tiers_mode=volume) |
tier_up_to |
list of decimal (string) | Upper limit of each tier except the last, inclusive and increasing. The first tier covers 0 up to the first limit, the next tier starts just above it, and the last tier has no limit (Stripe's up_to=inf), so give one item fewer than tier_unit_price. Omit it for a single tier. Up to 99 items. Each item: > 0 and <= 1000000000000000. |
tier_unit_price required |
list of decimal (string) | Price per unit in each tier, first tier first (any number of decimals, like Stripe's unit_amount_decimal). 1 to 100 items. Each item: >= 0 and <= 1000000000000000. Unit: currency. |
tier_flat_fee |
list of decimal (string) | Flat fee of each tier, one per tier like tier_unit_price (Stripe's flat_amount). Omit it for no flat fees. Up to 100 items. Each item: >= 0 and <= 1000000000000000. Unit: currency. |
options.rounding |
half_even | half_up | half_down | up | down | ceiling | floor | Rounding mode applied once to each result. Default half_up. |
options.decimals |
integer | Round results to this many digits after the decimal point. |
Result
Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.
| Result | Type | Description |
|---|---|---|
total | decimal (string) | The price of the quantity, rounded once. Unit: currency. |
tier | integer | The tier the quantity lands in (volume) or the highest tier it reaches (graduated). |
tiers | list of object | Each tier that is charged: one row for volume pricing, every tier reached for graduated pricing. |
Examples
Stripe example, graduated: 20 units on 1–5 at $7, 6–10 at $6.50, 11+ at $6
curl https://api.curatedapi.com/v1/calc/billing/tiered-price \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"quantity": "20",
"pricing_model": "graduated",
"tier_up_to": ["5", "10"],
"tier_unit_price": ["7", "6.5", "6"]
}'
{
"calculator": "billing/tiered-price@1",
"result": {
"total": "127.50",
"tier": 3,
"tiers": [
{
"tier": 1,
"above": "0",
"up_to": "5",
"units": "5",
"unit_price": "7",
"flat_fee": "0",
"amount": "35.00"
},
{
"tier": 2,
"above": "5",
"up_to": "10",
"units": "5",
"unit_price": "6.5",
"flat_fee": "0",
"amount": "32.50"
},
{
"tier": 3,
"above": "10",
"up_to": "inf",
"units": "10",
"unit_price": "6",
"flat_fee": "0",
"amount": "60.00"
}
]
},
"exactness": {
"total": "exact"
},
"precision": {
"rounding": "half_up",
"decimals": 2
},
"inputs": {
"quantity": "20",
"pricing_model": "graduated",
"tier_up_to": [
"5",
"10"
],
"tier_unit_price": [
"7",
"6.5",
"6"
]
},
"formula": "graduated: Σ over tiers reached (min(q, up_to_k) − up_to_(k−1)) × price_k + fee_k; volume: q × price_k + fee_k for the first tier with q ≤ up_to_k",
"references": [
{
"title": "Stripe: Set up tiered pricing (volume and graduated tiers, flat amounts, quantity 0)",
"url": "https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing"
},
{
"title": "Stripe API: Price tiers (up_to, unit_amount_decimal, flat_amount)",
"url": "https://docs.stripe.com/api/prices/object"
}
],
"warnings": []
}
Stripe example, volume: 20 units on the same tiers
curl https://api.curatedapi.com/v1/calc/billing/tiered-price \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"quantity": "20",
"pricing_model": "volume",
"tier_up_to": ["5", "10"],
"tier_unit_price": ["7", "6.5", "6"]
}'
{
"calculator": "billing/tiered-price@1",
"result": {
"total": "120.00",
"tier": 3,
"tiers": [
{
"tier": 3,
"above": "10",
"up_to": "inf",
"units": "20",
"unit_price": "6",
"flat_fee": "0",
"amount": "120.00"
}
]
},
"exactness": {
"total": "exact"
},
"precision": {
"rounding": "half_up",
"decimals": 2
},
"inputs": {
"quantity": "20",
"pricing_model": "volume",
"tier_up_to": [
"5",
"10"
],
"tier_unit_price": [
"7",
"6.5",
"6"
]
},
"formula": "graduated: Σ over tiers reached (min(q, up_to_k) − up_to_(k−1)) × price_k + fee_k; volume: q × price_k + fee_k for the first tier with q ≤ up_to_k",
"references": [
{
"title": "Stripe: Set up tiered pricing (volume and graduated tiers, flat amounts, quantity 0)",
"url": "https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing"
},
{
"title": "Stripe API: Price tiers (up_to, unit_amount_decimal, flat_amount)",
"url": "https://docs.stripe.com/api/prices/object"
}
],
"warnings": []
}
Stripe example with flat fees, graduated: 12 units
curl https://api.curatedapi.com/v1/calc/billing/tiered-price \
-H "Authorization: Bearer $CURATEDAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"quantity": "12",
"pricing_model": "graduated",
"tier_up_to": ["5", "10", "15", "20"],
"tier_unit_price": ["5", "4", "3", "2", "1"],
"tier_flat_fee": ["10", "20", "30", "40", "50"]
}'
{
"calculator": "billing/tiered-price@1",
"result": {
"total": "111.00",
"tier": 3,
"tiers": [
{
"tier": 1,
"above": "0",
"up_to": "5",
"units": "5",
"unit_price": "5",
"flat_fee": "10",
"amount": "35.00"
},
{
"tier": 2,
"above": "5",
"up_to": "10",
"units": "5",
"unit_price": "4",
"flat_fee": "20",
"amount": "40.00"
},
{
"tier": 3,
"above": "10",
"up_to": "15",
"units": "2",
"unit_price": "3",
"flat_fee": "30",
"amount": "36.00"
}
]
},
"exactness": {
"total": "exact"
},
"precision": {
"rounding": "half_up",
"decimals": 2
},
"inputs": {
"quantity": "12",
"pricing_model": "graduated",
"tier_up_to": [
"5",
"10",
"15",
"20"
],
"tier_unit_price": [
"5",
"4",
"3",
"2",
"1"
],
"tier_flat_fee": [
"10",
"20",
"30",
"40",
"50"
]
},
"formula": "graduated: Σ over tiers reached (min(q, up_to_k) − up_to_(k−1)) × price_k + fee_k; volume: q × price_k + fee_k for the first tier with q ≤ up_to_k",
"references": [
{
"title": "Stripe: Set up tiered pricing (volume and graduated tiers, flat amounts, quantity 0)",
"url": "https://docs.stripe.com/subscriptions/pricing-models/tiered-pricing"
},
{
"title": "Stripe API: Price tiers (up_to, unit_amount_decimal, flat_amount)",
"url": "https://docs.stripe.com/api/prices/object"
}
],
"warnings": []
}
References
- Stripe: Set up tiered pricing (volume and graduated tiers, flat amounts, quantity 0)
- Stripe API: Price tiers (up_to, unit_amount_decimal, flat_amount)
Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.
Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.