curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

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

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

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

ResultTypeDescription
totaldecimal (string)The price of the quantity, rounded once. Unit: currency.
tierintegerThe tier the quantity lands in (volume) or the highest tier it reaches (graduated).
tierslist of objectEach 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

Requestcurl
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"]
  }'
200 OKResponse
{
  "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

Requestcurl
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"]
  }'
200 OKResponse
{
  "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

Requestcurl
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"]
  }'
200 OKResponse
{
  "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

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.