curatedapi

Money splitter

Split an amount by ratios or into equal parts so the shares are whole cents and add up exactly to the amount.

The amount to split. A negative amount (a refund) is split the same way and every share is negative.
ISO 4217 code of the currency, such as USD, EUR, JPY or KWD. It sets the number of decimals (the minor unit): 2 for most currencies, 0 for JPY, 3 for KWD. At most 3 characters.
The parts' ratios, in order. Only their proportions matter: [70, 30], [7, 3] and [0.7, 0.3] split the same way. A ratio of 0 gets nothing. Give ratios or parts. 1 to 1000 items. One per line, or separated by commas.
Number of equal parts (instead of ratios).
Who gets the minor units left over after every share is rounded down. Options: largest_remainder: the leftover minor units go to the parts whose exact shares were cut the most, earlier parts first on a tie (Hamilton's method); in_order: the leftover minor units go to the first parts, one each, skipping parts with a ratio of 0 (the rule of Dinero.js and Martin Fowler's Money pattern)
How to round the amount to the currency's minor unit first, if it has more decimals (a warning says so). Options: half_up: to nearest, ties away from zero (2.5 → 3, -2.5 → -3); half_even: to nearest, ties to even (2.5 → 2, 3.5 → 4): banker's rounding; half_down: to nearest, ties towards zero (2.5 → 2); up: away from zero (2.1 → 3, -2.1 → -3); down: towards zero, i.e. truncate (2.9 → 2); ceiling: towards +∞ (2.1 → 3, -2.1 → -2); floor: towards −∞ (2.9 → 2, -2.1 → -3)

Examples

Result: 100 USD split 70/20/10

Total
The amount that was split, in the currency's minor unit; the shares add up to exactly this.
100.00
Shares
The shares, in the order of the parts.
70.00, 20.00, 10.00
Leftover units
How many minor units were left after rounding every share down, and handed out one each.
0
Decimals
The currency's number of decimals (ISO 4217 minor unit).
2

Allocation

PartRatioExact shareShareExtra unit
1707070.00no
2202020.00no
3101010.00no

Calculator money/allocate@1.

How it is calculated

units = amount × 10^decimals; share_i = ⌊units × r_i ÷ Σr⌋, then the units − Σshare_i leftover units go one each to the largest remainders (or the first parts)

Splits an amount of money between several parts, by ratios (70/30, 1:2:3, percentages) or into equal parts, so that every share is a whole number of the currency's minor unit and the shares add up to the amount exactly: no cent is lost or invented. Rounding each share on its own does not work: 10.00 split three ways rounds to 3.33 three times, which is 9.99. Here each part first gets its exact share rounded down, and the few cents left over are handed out one at a time. Use it for splitting bills, revenue shares, commission, refunds across order lines, or a discount across invoice lines. The currency sets the minor unit: cents for USD and EUR, whole yen for JPY, fils (0.001) for KWD.

  • The shares always add up to the amount exactly.
  • With largest_remainder (the default), the leftover units go to the parts whose exact shares lost the most when rounded down, so every share is less than one minor unit from its exact share. With in_order they go to the first parts with a ratio above 0, as in Dinero.js, even if a part's exact share was already a whole number of cents, so a share can be a full minor unit off. Both give the same result for equal parts.
  • A negative amount is split as if it were positive and every share is made negative, so a refund mirrors the charge.
  • To split a whole invoice line by line (for example a discount across items), use the line amounts as the ratios.

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Use it from your code

POST /v1/calc/money/allocateVersion 1
curl https://api.curatedapi.com/v1/calc/money/allocate \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100",
    "currency": "USD",
    "ratios": ["70", "20", "10"]
  }'
The same call in Python
import os

import requests

payload = {
    "amount": "100",
    "currency": "USD",
    "ratios": ["70", "20", "10"],
}
response = requests.post(
    "https://api.curatedapi.com/v1/calc/money/allocate",
    headers={"Authorization": f"Bearer {os.environ['CURATEDAPI_KEY']}"},
    json=payload,
    timeout=10,
)
print(response.json()["result"])
The same call in JavaScript
const payload = {
    "amount": "100",
    "currency": "USD",
    "ratios": ["70", "20", "10"],
};
const response = await fetch("https://api.curatedapi.com/v1/calc/money/allocate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CURATEDAPI_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
console.log((await response.json()).result);

MCP tool calc_money_allocate at https://mcp.curatedapi.com. Inputs, outputs and errors in the API reference.

Put it on your website

<div data-curatedapi-widget="money/allocate" data-key="capi_public_…"></div>
<script src="https://widgets.curatedapi.com/v1/widget.js" async></script>

Use a public key registered for your site. Calculations are billed like API calls. How widgets work.

Related calculators

Round and split money to the cent in your app

Every share adds up to the total and every cash total follows the country's rule, so the ledger, the receipt and the payout agree.

Free for up to 1,000 payments a month. 50,000 payments a month cost $9.00 on the Starter plan.