# Proration compute

`proration-compute` · version 1.0.0 · Money & pricing · free, no key needed

Prorate an amount by used days over period days (counts or ISO dates) into prorated and remaining parts that add up.

**Use when you need to: 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.**

## Decide before calling

Read the [versioned contract](/v1/tools/proration-compute/versions/1.0.0) and the supported scope below. Reuse `proration-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 `proration-compute@1.0.0` for prorate a monthly fee for 12 days of 30. 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

- 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

## Not supported

- 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

## Behavior

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

## Input

- `amount` (string, required): min length 1; max length 62; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`; Full-period amount to prorate (signed decimal; credits may be negative), a multiple of the currency minor unit.
- `period_start` (string, optional): min length 10; max length 62; pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`; Date mode: first day of the billing period, YYYY-MM-DD (proleptic Gregorian, years 0001-9999).
- `period_end` (string, optional): min length 10; max length 62; pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`; Date mode: end of the billing period (exclusive by default; last day when end_inclusive is true).
- `usage_start` (string, optional): min length 10; max length 62; pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`; Date mode: first day of the prorated (used) span; must not precede period_start.
- `usage_end` (string, optional): min length 10; max length 62; pattern `^[0-9]{4}-[0-9]{2}-[0-9]{2}$`; Date mode: end of the used span (same inclusive/exclusive convention); must not exceed period_end.
- `end_inclusive` (boolean, optional): default `false`; Date mode only: count the end dates as included days (days = end - start + 1). Default false (days = end - start).
- `used_days` (integer, optional): min 0; max 3652059; Count mode: days used (0 to period_days).
- `period_days` (integer, optional): min 1; max 3652059; Count mode: days in the whole period.
- `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

- `prorated_amount` (string, required): min length 1; max length 400; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`; round(amount x used_days / period_days) at the scale, one rounding.
- `remaining_amount` (string, required): min length 1; max length 400; pattern `^-?(0|[1-9][0-9]*)(\.[0-9]+)?$`; amount - prorated_amount, exact at the scale.
- `used_days` (integer, required): min 0; max 3652059
- `period_days` (integer, required): min 1; max 3652059
- `fraction` (object, required)
- `exact` (boolean, required): True when prorated_amount needed no rounding.
- `currency` (string or null, required): pattern `^[A-Z]{3}$`
- `scale` (integer, required): min 0; max 18
- `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 days: 3652059

## Example

Request input:

```json
{
  "amount": "30.00",
  "used_days": 12,
  "period_days": 30,
  "currency": "USD",
  "rounding": "half_even"
}
```

Response:

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

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "proration-compute",
  "version": "1.0.0",
  "input": {
    "amount": "30.00",
    "used_days": 12,
    "period_days": 30,
    "currency": "USD",
    "rounding": "half_even"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/proration-compute/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"amount":"30.00","used_days":12,"period_days":30,"currency":"USD","rounding":"half_even"}'
```

The machine-readable contract is at [/v1/tools/proration-compute/versions/1.0.0](/v1/tools/proration-compute/versions/1.0.0).

### CLI

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

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

## Related tools

- [Tiered price compute](/tools/tiered-price-compute): Compute a total price for a quantity under graduated or volume tiers with inclusive bounds and optional flat fees.
- [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.
- [Fraction to decimal expand](/tools/fraction-to-decimal-expand): Expand an integer fraction into its exact decimal with the minimal repeating block marked, e.g. 1/7 as 0.(142857).
- [Percent compute](/tools/percent-compute): Exact percentage of, ratio, change, increase, decrease and reverse percentage, rounded once at a chosen scale.
- [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.
- [Currency lookup](/tools/currency-lookup): Look up an ISO 4217 alphabetic or numeric currency code: name, minor-unit exponent, entities, active or withdrawn.