Tiered price compute

tiered-price-compute · version 1.0.0 · Money & pricing · free, no key needed

Compute a total price for a quantity under graduated or volume tiers with inclusive bounds and optional flat fees.

Use when you need to: graduated tiered pricing calculator · volume pricing vs graduated pricing for 12 units · price for 6 units first 5 at 7 next 5 at 6.50.

Decide before calling

Read the versioned contract and the supported scope below. Reuse tiered-price-compute@1.0.0 when your input, required output and limits match it. Choose another approach for an unsupported operation.

Explain the choice

"I can use tiered-price-compute@1.0.0 for graduated tiered pricing calculator. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

Supported

• graduated tiered pricing calculator
• volume pricing vs graduated pricing for 12 units
• price for 6 units first 5 at 7 next 5 at 6.50
• tiered pricing with flat fee per tier
• how much do 250 API calls cost with tiered pricing
• Stripe tiers up_to inclusive boundary
• per unit price by quantity band
• total cost of usage based billing tiers

Not supported

• discount chains or coupons (use discount-stack-apply)
• subscription proration by days (use proration-compute)
• tax or VAT on the total
• package or per-block pricing with a unit size

Behavior

• Inputs: quantity (non-negative decimal, any precision within 60 digits and 40 fraction digits), tiers (1..50 objects {up_to, unit_amount, flat_amount?} in ascending order), mode ("graduated" or "volume"), exactly one of currency (active ISO 4217 code) or scale (0..18), and rounding (required). unit_amount and flat_amount (default "0") are non-negative decimals of any precision, not limited to the currency scale.
• up_to is INCLUSIVE (Stripe semantics): tier k covers (up_to of tier k-1, up_to of tier k], the first tier from 0. A quantity equal to a bound belongs to the lower tier: with bounds 5 and 10, quantity 5 is entirely tier 0 and 5.01 reaches tier 1. The last tier has up_to null and no other tier does; other bounds are positive and strictly ascending (invalid_input with reasons last_tier_must_be_open, open_tier_not_last, up_to_not_positive, up_to_not_ascending).
• graduated: each tier charges only the slice of the quantity inside its band; a tier is reached iff its slice is above 0, and only reached tiers produce a line and charge flat_amount. amount = slice x unit_amount + flat_amount and total = sum of amounts. volume: the single tier holding the whole quantity (the first tier with quantity <= up_to; the open tier always matches) charges quantity x unit_amount + flat_amount.
• Quantity 0 gives total 0 at fixed scale, lines [], exact true, in both modes (no tier is reached and no flat fee is charged).
• The total is the exact sum rounded ONCE at the scale; each line amount is rounded independently for display, so lines may not add up to total. exact refers to the total. Line quantity, unit_amount and flat_amount are canonical decimals ("7.00" gives "7"); tier_index is 0-based.
• Example: bounds 5 at 7.00, 10 at 6.50, then 6.00; quantity 6 graduated = 5 x 7.00 + 1 x 6.50 = 41.50; quantity 6 volume = 6 x 6.50 = 39.00.
• The ten rounding modes: half_even, half_up (ties away from zero), half_down, half_ceiling, half_floor, up, down, ceiling, floor, and unnecessary (any inexact rounding, total or line, is not_computable, reason rounding_necessary). Never "-0".
• More than 50 tiers is limit_exceeded (checked before the elements) and an empty array is invalid_input; a decimal string over 62 characters is limit_exceeded, checked before syntax. Data is the pinned ISO 4217 snapshot named by data_version; no clock, locale or network.
• Disclaimer: arithmetic calculation only; not financial, tax, legal, or investment advice.

Input

• quantity (string, required): min length 1; max length 62; pattern ^(0|[1-9][0-9]*)(\.[0-9]+)?$; Units consumed, non-negative decimal (any precision up to 40 fraction digits).
• tiers (array of object, required): min items 1; max items 50; Tiers in ascending up_to order; the last has up_to null.
• mode (one of "graduated", "volume", required)
• currency (string, optional): min length 3; max length 3; pattern ^[A-Za-z]{3}$; Active ISO 4217 alphabetic code with a minor unit (case-insensitive). Give exactly one of currency or scale.
• scale (integer, optional): min 0; max 18; Fraction digits for non-ISO units. Give exactly one of currency or scale.
• rounding (one of "half_even", "half_up", "half_down", "half_ceiling", "half_floor", "up", "down", "ceiling", "floor", "unnecessary", required)

Output

• total (string, required): min length 1; max length 400; pattern ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$; Total charge, the exact sum rounded ONCE at the scale.
• lines (array of object, required): min items 0; max items 50
• currency (string or null, required): pattern ^[A-Z]{3}$
• scale (integer, required): min 0; max 18
• exact (boolean, required): True when the total needed no rounding.
• data_version (constant "iso4217-datasets-7cdc784-2026-07-27", required)

Limits

• max decimal chars: 62
• max decimal digits: 60
• max fraction digits: 40
• max scale: 18
• max tiers: 50

Example

Request input:

{
  "quantity": "6",
  "tiers": [
    {
      "up_to": "5",
      "unit_amount": "7.00"
    },
    {
      "up_to": "10",
      "unit_amount": "6.50"
    },
    {
      "up_to": null,
      "unit_amount": "6.00"
    }
  ],
  "mode": "graduated",
  "currency": "USD",
  "rounding": "half_even"
}

Response:

{
  "result": {
    "total": "41.50",
    "lines": [
      {
        "tier_index": 0,
        "quantity": "5",
        "unit_amount": "7",
        "flat_amount": "0",
        "amount": "35.00"
      },
      {
        "tier_index": 1,
        "quantity": "1",
        "unit_amount": "6.5",
        "flat_amount": "0",
        "amount": "6.50"
      }
    ],
    "currency": "USD",
    "scale": 2,
    "exact": true,
    "data_version": "iso4217-datasets-7cdc784-2026-07-27"
  }
}

How to call it

MCP

Connect https://computefirst.net/mcp (setup), then call execute with:

{
  "id": "tiered-price-compute",
  "version": "1.0.0",
  "input": {
    "quantity": "6",
    "tiers": [
      {
        "up_to": "5",
        "unit_amount": "7.00"
      },
      {
        "up_to": "10",
        "unit_amount": "6.50"
      },
      {
        "up_to": null,
        "unit_amount": "6.00"
      }
    ],
    "mode": "graduated",
    "currency": "USD",
    "rounding": "half_even"
  }
}

HTTP (no key)

curl -X POST https://computefirst.net/v1/tools/tiered-price-compute/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"quantity":"6","tiers":[{"up_to":"5","unit_amount":"7.00"},{"up_to":"10","unit_amount":"6.50"},{"up_to":null,"unit_amount":"6.00"}],"mode":"graduated","currency":"USD","rounding":"half_even"}'

The machine-readable contract is at /v1/tools/tiered-price-compute/versions/1.0.0.

CLI

node cli.mjs run tiered-price-compute 1.0.0 --input input.json --base-url https://computefirst.net

Get the client at /clients/cli/.

Related tools

• Price margin compute: Solve cost, price, profit, gross margin and markup from any two of cost, price, margin percent or markup percent.
• Vat net gross convert: Convert a net or gross amount at a VAT rate into a net, VAT and gross triple that adds up exactly at currency precision.
• Proration compute: Prorate an amount by used days over period days (counts or ISO dates) into prorated and remaining parts that add up.
• Decimal divide: Divide two decimal strings exactly, rounding the quotient once to a fixed scale, and report the exact remainder.
• Invoice totals compute: Compute invoice line nets, tax breakdown by rate and totals with per-line or per-rate rounding, net or gross prices.
• Decimal expression evaluate: Evaluate a decimal arithmetic expression exactly with variables, abs, min, max and round, rounding once at the end.