curatedapi

Tiered pricing calculator

Price of a quantity under graduated or volume tiers, with optional flat fees, exactly as Stripe bills tiered prices.

Number of units to price (whole or decimal, for metered usage).
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)
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. One per line, or separated by commas.
Price per unit in each tier, first tier first (any number of decimals, like Stripe's unit_amount_decimal). 1 to 100 items. One per line, or separated by commas.
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. One per line, or separated by commas.
More options: rounding and decimals
Precision and rounding
Rounding mode applied once to each result. Default half_up.
Round results to this many digits after the decimal point.

Examples

Result: Stripe example with flat fees, graduated: 12 units

Total
The price of the quantity, rounded once.
111.00 exact
Tier
The tier the quantity lands in (volume) or the highest tier it reaches (graduated).
3

Tiers

TierAboveUp toUnitsUnit priceFlat feeAmount
105551035.00
2510542040.00
31015233036.00

Rounding: Half up, 2 decimal places. Calculator billing/tiered-price@1.

How it is calculated

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

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.

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

References

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.

Use it from your code

POST /v1/calc/billing/tiered-priceVersion 1
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"]
  }'
The same call in Python
import os

import requests

payload = {
    "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"],
}
response = requests.post(
    "https://api.curatedapi.com/v1/calc/billing/tiered-price",
    headers={"Authorization": f"Bearer {os.environ['CURATEDAPI_KEY']}"},
    json=payload,
    timeout=10,
)
print(response.json()["result"])
The same call in JavaScript
const payload = {
    "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"],
};
const response = await fetch("https://api.curatedapi.com/v1/calc/billing/tiered-price", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CURATEDAPI_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
console.log((await response.json()).result);

MCP tool calc_billing_tiered_price at https://mcp.curatedapi.com. Inputs, outputs and errors in the API reference.

Put it on your website

<div data-curatedapi-widget="billing/tiered-price" data-key="capi_public_…"></div>
<script src="https://widgets.curatedapi.com/v1/widget.js" async></script>

Use a public key registered for your site. Calculations are billed like API calls. How widgets work.

Related calculators

Preview and check subscription charges

Show customers the exact charge before they change plan, or check an invoice before it goes out. Proration, tiers and stacked coupons follow the rules Stripe uses, to the cent.

Free for up to 1,000 charges priced a month. 50,000 charges priced a month cost $9.00 on the Starter plan.