# 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](/v1/tools/tiered-price-compute/versions/1.0.0) 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:

```json
{
  "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:

```json
{
  "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](/docs#connect)), then call `execute` with:

```json
{
  "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)

```sh
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](/v1/tools/tiered-price-compute/versions/1.0.0).

### CLI

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

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Price margin compute](/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](/tools/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](/tools/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](/tools/decimal-divide): Divide two decimal strings exactly, rounding the quotient once to a fixed scale, and report the exact remainder.
- [Invoice totals compute](/tools/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](/tools/decimal-expression-evaluate): Evaluate a decimal arithmetic expression exactly with variables, abs, min, max and round, rounding once at the end.