{"id":"proration-compute","version":"1.0.0","description":"Prorate an amount by used days over period days (counts or ISO dates) into prorated and remaining parts that add up.","supported_operations":["prorate a monthly fee for 12 days of 30","how much is the unused part of a subscription worth","partial month rent from March 10 to March 31","proration credit for mid cycle upgrade","prorated refund for leap year February","daily proration inclusive of end date","prorated amount used days over period days","fraction of billing period used"],"unsupported_operations":["business-day or working-day counts","30/360 or actual/365 interest day-count conventions","time-of-day or timezone based proration","tax, discounts or invoicing rules for the prorated amount"],"semantics":["Exactly one basis. DATE mode: period_start, period_end, usage_start, usage_end (YYYY-MM-DD, proleptic Gregorian, years 0001-9999) and optional end_inclusive (boolean, default false). COUNT mode: used_days and period_days as JSON integers, with no date field and no end_inclusive. Mixing (reason dates_and_counts_mixed), giving neither (no_proration_basis), an incomplete set (missing_field) or end_inclusive with counts (end_inclusive_with_counts) is invalid_input.","Day counts in date mode use the day ordinal (0001-01-01 = 1): days = end - start, plus 1 when end_inclusive is true, for both the period and the used span. Exclusive: 2026-04-01 to 2026-05-01 is 30 days and 2024-02-01 to 2024-03-01 is 29. Inclusive: 2026-04-01 to 2026-04-30 is 30 days. period_days must be at least 1 (reason period_not_positive) and period_start <= usage_start <= usage_end <= period_end (reason usage_outside_period).","Dates are exact 4-2-2 digit strings; a bad calendar date (year 0000, month 13, Feb 30, Feb 29 in a non-leap year) is invalid_input with reason invalid_date, a bad shape is date_syntax, and a date string over 62 characters is limit_exceeded, checked before the shape. Leap years: divisible by 4 except centuries not divisible by 400.","Counts: period_days is 1..3652059 and used_days 0..3652059; a value above 3652059 is limit_exceeded; a negative used_days or period_days below 1 is invalid_input (out_of_range); a non-integer or non-number is invalid_input (not_integer); used_days above period_days is invalid_input (used_exceeds_period).","prorated_amount = round(amount x used_days / period_days) once at the scale with the required rounding mode (multiply first, divide once, never round a daily rate); remaining_amount = amount - prorated_amount exactly, so the two always sum to amount. amount is signed and must be a multiple of the minor unit by value; a negative amount prorates to a negative amount and tie modes act on the sign.","fraction is used_days/period_days in lowest terms (0/1 for no usage, 1/1 for the full period). used_days and period_days in the output are the counts actually used. exact is true iff no rounding was needed.","The ten rounding modes: half_even, half_up (ties away from zero), half_down, half_ceiling, half_floor, up, down, ceiling, floor, and unnecessary (an inexact result is not_computable, reason rounding_necessary). Exactly one of currency (active ISO 4217 code) or scale (0..18) is required; outputs have exactly scale fraction digits.","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_days":3652059},"pricing":{"status":"unpriced","charge_usd":null},"input_schema":{"type":"object","additionalProperties":false,"required":["amount","rounding"],"properties":{"amount":{"type":"string","minLength":1,"maxLength":62,"pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"Full-period amount to prorate (signed decimal; credits may be negative), a multiple of the currency minor unit."},"period_start":{"type":"string","minLength":10,"maxLength":62,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","description":"Date mode: first day of the billing period, YYYY-MM-DD (proleptic Gregorian, years 0001-9999)."},"period_end":{"type":"string","minLength":10,"maxLength":62,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","description":"Date mode: end of the billing period (exclusive by default; last day when end_inclusive is true)."},"usage_start":{"type":"string","minLength":10,"maxLength":62,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","description":"Date mode: first day of the prorated (used) span; must not precede period_start."},"usage_end":{"type":"string","minLength":10,"maxLength":62,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","description":"Date mode: end of the used span (same inclusive/exclusive convention); must not exceed period_end."},"end_inclusive":{"type":"boolean","default":false,"description":"Date mode only: count the end dates as included days (days = end - start + 1). Default false (days = end - start)."},"used_days":{"type":"integer","minimum":0,"maximum":3652059,"description":"Count mode: days used (0 to period_days)."},"period_days":{"type":"integer","minimum":1,"maximum":3652059,"description":"Count mode: days in the whole period."},"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":["prorated_amount","remaining_amount","used_days","period_days","fraction","exact","currency","scale","data_version"],"properties":{"prorated_amount":{"type":"string","minLength":1,"maxLength":400,"pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"round(amount x used_days / period_days) at the scale, one rounding."},"remaining_amount":{"type":"string","minLength":1,"maxLength":400,"pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","description":"amount - prorated_amount, exact at the scale."},"used_days":{"type":"integer","minimum":0,"maximum":3652059},"period_days":{"type":"integer","minimum":1,"maximum":3652059},"fraction":{"type":"object","additionalProperties":false,"required":["numerator","denominator"],"properties":{"numerator":{"type":"integer","minimum":0,"maximum":3652059},"denominator":{"type":"integer","minimum":1,"maximum":3652059}}},"exact":{"type":"boolean","description":"True when prorated_amount needed no rounding."},"currency":{"type":["string","null"],"pattern":"^[A-Z]{3}$"},"scale":{"type":"integer","minimum":0,"maximum":18},"data_version":{"type":"string","const":"iso4217-datasets-7cdc784-2026-07-27"}}},"examples":[{"input":{"amount":"30.00","used_days":12,"period_days":30,"currency":"USD","rounding":"half_even"},"output":{"prorated_amount":"12.00","remaining_amount":"18.00","used_days":12,"period_days":30,"fraction":{"numerator":2,"denominator":5},"exact":true,"currency":"USD","scale":2,"data_version":"iso4217-datasets-7cdc784-2026-07-27"}},{"input":{"amount":"1450.00","period_start":"2024-02-01","period_end":"2024-03-01","usage_start":"2024-02-10","usage_end":"2024-03-01","currency":"USD","rounding":"half_up"},"output":{"prorated_amount":"1000.00","remaining_amount":"450.00","used_days":20,"period_days":29,"fraction":{"numerator":20,"denominator":29},"exact":true,"currency":"USD","scale":2,"data_version":"iso4217-datasets-7cdc784-2026-07-27"}},{"input":{"amount":"99.00","period_start":"2026-04-01","period_end":"2026-04-30","usage_start":"2026-04-13","usage_end":"2026-04-30","end_inclusive":true,"scale":2,"rounding":"down"},"output":{"prorated_amount":"59.40","remaining_amount":"39.60","used_days":18,"period_days":30,"fraction":{"numerator":3,"denominator":5},"exact":true,"currency":null,"scale":2,"data_version":"iso4217-datasets-7cdc784-2026-07-27"}}],"execute_url":"/v1/tools/proration-compute/versions/1.0.0/execute"}