{"id":"tiered-price-compute","version":"1.0.0","description":"Compute a total price for a quantity under graduated or volume tiers with inclusive bounds and optional flat fees.","supported_operations":["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"],"unsupported_operations":["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"],"semantics":["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."],"limits":{"max_decimal_chars":62,"max_decimal_digits":60,"max_fraction_digits":40,"max_scale":18,"max_tiers":50},"pricing":{"status":"unpriced","charge_usd":null},"input_schema":{"type":"object","additionalProperties":false,"required":["quantity","tiers","mode","rounding"],"properties":{"quantity":{"type":"string","minLength":1,"maxLength":62,"pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"Units consumed, non-negative decimal (any precision up to 40 fraction digits)."},"tiers":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["up_to","unit_amount"],"properties":{"up_to":{"type":["string","null"],"minLength":1,"maxLength":62,"pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"Inclusive upper bound of the tier (positive); null (open-ended) on the last tier and only there."},"unit_amount":{"type":"string","minLength":1,"maxLength":62,"pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"Price per unit in this tier; any precision (not limited to the currency scale)."},"flat_amount":{"type":"string","minLength":1,"maxLength":62,"pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"Flat fee charged once when this tier is used; any precision. Default \"0\".","default":"0"}}},"description":"Tiers in ascending up_to order; the last has up_to null."},"mode":{"type":"string","enum":["graduated","volume"]},"currency":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[A-Za-z]{3}$","description":"Active ISO 4217 alphabetic code with a minor unit (case-insensitive). Give exactly one of currency or scale."},"scale":{"type":"integer","minimum":0,"maximum":18,"description":"Fraction digits for non-ISO units. Give exactly one of currency or scale."},"rounding":{"type":"string","enum":["half_even","half_up","half_down","half_ceiling","half_floor","up","down","ceiling","floor","unnecessary"]}}},"output_schema":{"type":"object","additionalProperties":false,"required":["total","lines","currency","scale","exact","data_version"],"properties":{"total":{"type":"string","minLength":1,"maxLength":400,"pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"Total charge, the exact sum rounded ONCE at the scale."},"lines":{"type":"array","minItems":0,"maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["tier_index","quantity","unit_amount","flat_amount","amount"],"properties":{"tier_index":{"type":"integer","minimum":0,"maximum":49},"quantity":{"type":"string","minLength":1,"maxLength":400,"pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"Units charged in this tier (graduated: the slice; volume: the whole quantity), canonical."},"unit_amount":{"type":"string","minLength":1,"maxLength":400,"pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"Canonical."},"flat_amount":{"type":"string","minLength":1,"maxLength":400,"pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"Canonical."},"amount":{"type":"string","minLength":1,"maxLength":400,"pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"quantity x unit_amount + flat_amount rounded on its own for display; lines need not sum to total."}}}},"currency":{"type":["string","null"],"pattern":"^[A-Z]{3}$"},"scale":{"type":"integer","minimum":0,"maximum":18},"exact":{"type":"boolean","description":"True when the total needed no rounding."},"data_version":{"type":"string","const":"iso4217-datasets-7cdc784-2026-07-27"}}},"examples":[{"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"},"output":{"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"}},{"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":"volume","currency":"USD","rounding":"half_even"},"output":{"total":"39.00","lines":[{"tier_index":1,"quantity":"6","unit_amount":"6.5","flat_amount":"0","amount":"39.00"}],"currency":"USD","scale":2,"exact":true,"data_version":"iso4217-datasets-7cdc784-2026-07-27"}},{"input":{"quantity":"12","tiers":[{"up_to":"5","unit_amount":"5","flat_amount":"10"},{"up_to":"10","unit_amount":"4","flat_amount":"20"},{"up_to":null,"unit_amount":"3","flat_amount":"30"}],"mode":"graduated","scale":2,"rounding":"half_up"},"output":{"total":"111.00","lines":[{"tier_index":0,"quantity":"5","unit_amount":"5","flat_amount":"10","amount":"35.00"},{"tier_index":1,"quantity":"5","unit_amount":"4","flat_amount":"20","amount":"40.00"},{"tier_index":2,"quantity":"2","unit_amount":"3","flat_amount":"30","amount":"36.00"}],"currency":null,"scale":2,"exact":true,"data_version":"iso4217-datasets-7cdc784-2026-07-27"}}],"execute_url":"/v1/tools/tiered-price-compute/versions/1.0.0/execute"}