curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

Money splitter API

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

POST https://api.curatedapi.com/v1/calc/money/allocate

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.

Formula

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

Inputs

Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).

InputTypeDescription
amount required decimal (string) The amount to split. A negative amount (a refund) is split the same way and every share is negative. Allowed: >= -1000000000000000 and <= 1000000000000000. Unit: currency.
currency required string 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.
ratios list of decimal (string) 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. Each item: >= 0 and <= 1000000000000000.
parts integer Number of equal parts (instead of ratios). Allowed: >= 1 and <= 1000.
method largest_remainder | in_order
default largest_remainder
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)
rounding half_up | half_even | half_down | up | down | ceiling | floor
default half_up
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)

Result

Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.

ResultTypeDescription
totalstringThe amount that was split, in the currency's minor unit; the shares add up to exactly this.
shareslist of stringThe shares, in the order of the parts.
leftover_unitsintegerHow many minor units were left after rounding every share down, and handed out one each.
decimalsintegerThe currency's number of decimals (ISO 4217 minor unit).
allocationlist of objectEach part: ratio, exact share and share.

Examples

100 USD split 70/20/10

Requestcurl
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"]
  }'
200 OKResponse
{
  "calculator": "money/allocate@1",
  "result": {
    "total": "100.00",
    "shares": [
      "70.00",
      "20.00",
      "10.00"
    ],
    "leftover_units": 0,
    "decimals": 2,
    "allocation": [
      {
        "part": 1,
        "ratio": "70",
        "exact_share": "70",
        "share": "70.00",
        "extra_unit": false
      },
      {
        "part": 2,
        "ratio": "20",
        "exact_share": "20",
        "share": "20.00",
        "extra_unit": false
      },
      {
        "part": 3,
        "ratio": "10",
        "exact_share": "10",
        "share": "10.00",
        "extra_unit": false
      }
    ]
  },
  "exactness": {},
  "precision": null,
  "inputs": {
    "amount": "100",
    "currency": "USD",
    "ratios": [
      "70",
      "20",
      "10"
    ],
    "method": "largest_remainder",
    "rounding": "half_up"
  },
  "formula": "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)",
  "references": [
    {
      "title": "Dinero.js: allocate (10.03 split 50/50 gives 5.02 and 5.01; a ratio of 0 gets nothing)",
      "url": "https://www.dinerojs.com/api/mutations/allocate"
    },
    {
      "title": "Largest remainder method (Hamilton's method), with a worked example",
      "url": "https://en.wikipedia.org/wiki/Quota_method"
    },
    {
      "title": "ISO 4217 List One, current currencies and funds (SIX, the maintenance agency)",
      "url": "https://www.six-group.com/en/products-services/financial-information/market-reference-data/data-standards.html"
    },
    {
      "title": "ISO 4217 amendment 180: Bulgaria adopts the euro (1 January 2026)",
      "url": "https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/amendments/dl-currency-iso-amendment-180.pdf"
    }
  ],
  "warnings": []
}

10 USD in 3 equal parts

Requestcurl
curl https://api.curatedapi.com/v1/calc/money/allocate \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10",
    "currency": "USD",
    "parts": 3
  }'
200 OKResponse
{
  "calculator": "money/allocate@1",
  "result": {
    "total": "10.00",
    "shares": [
      "3.34",
      "3.33",
      "3.33"
    ],
    "leftover_units": 1,
    "decimals": 2,
    "allocation": [
      {
        "part": 1,
        "ratio": "1",
        "exact_share": "10/3",
        "share": "3.34",
        "extra_unit": true
      },
      {
        "part": 2,
        "ratio": "1",
        "exact_share": "10/3",
        "share": "3.33",
        "extra_unit": false
      },
      {
        "part": 3,
        "ratio": "1",
        "exact_share": "10/3",
        "share": "3.33",
        "extra_unit": false
      }
    ]
  },
  "exactness": {},
  "precision": null,
  "inputs": {
    "amount": "10",
    "currency": "USD",
    "parts": 3,
    "method": "largest_remainder",
    "rounding": "half_up"
  },
  "formula": "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)",
  "references": [
    {
      "title": "Dinero.js: allocate (10.03 split 50/50 gives 5.02 and 5.01; a ratio of 0 gets nothing)",
      "url": "https://www.dinerojs.com/api/mutations/allocate"
    },
    {
      "title": "Largest remainder method (Hamilton's method), with a worked example",
      "url": "https://en.wikipedia.org/wiki/Quota_method"
    },
    {
      "title": "ISO 4217 List One, current currencies and funds (SIX, the maintenance agency)",
      "url": "https://www.six-group.com/en/products-services/financial-information/market-reference-data/data-standards.html"
    },
    {
      "title": "ISO 4217 amendment 180: Bulgaria adopts the euro (1 January 2026)",
      "url": "https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/amendments/dl-currency-iso-amendment-180.pdf"
    }
  ],
  "warnings": []
}

0.05 EUR split 70/30, largest remainder

Requestcurl
curl https://api.curatedapi.com/v1/calc/money/allocate \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "0.05",
    "currency": "EUR",
    "ratios": ["70", "30"]
  }'
200 OKResponse
{
  "calculator": "money/allocate@1",
  "result": {
    "total": "0.05",
    "shares": [
      "0.04",
      "0.01"
    ],
    "leftover_units": 1,
    "decimals": 2,
    "allocation": [
      {
        "part": 1,
        "ratio": "70",
        "exact_share": "0.035",
        "share": "0.04",
        "extra_unit": true
      },
      {
        "part": 2,
        "ratio": "30",
        "exact_share": "0.015",
        "share": "0.01",
        "extra_unit": false
      }
    ]
  },
  "exactness": {},
  "precision": null,
  "inputs": {
    "amount": "0.05",
    "currency": "EUR",
    "ratios": [
      "70",
      "30"
    ],
    "method": "largest_remainder",
    "rounding": "half_up"
  },
  "formula": "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)",
  "references": [
    {
      "title": "Dinero.js: allocate (10.03 split 50/50 gives 5.02 and 5.01; a ratio of 0 gets nothing)",
      "url": "https://www.dinerojs.com/api/mutations/allocate"
    },
    {
      "title": "Largest remainder method (Hamilton's method), with a worked example",
      "url": "https://en.wikipedia.org/wiki/Quota_method"
    },
    {
      "title": "ISO 4217 List One, current currencies and funds (SIX, the maintenance agency)",
      "url": "https://www.six-group.com/en/products-services/financial-information/market-reference-data/data-standards.html"
    },
    {
      "title": "ISO 4217 amendment 180: Bulgaria adopts the euro (1 January 2026)",
      "url": "https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/amendments/dl-currency-iso-amendment-180.pdf"
    }
  ],
  "warnings": []
}

1000 JPY in 3 parts (yen have no decimals)

Requestcurl
curl https://api.curatedapi.com/v1/calc/money/allocate \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1000",
    "currency": "JPY",
    "parts": 3
  }'
200 OKResponse
{
  "calculator": "money/allocate@1",
  "result": {
    "total": "1000",
    "shares": [
      "334",
      "333",
      "333"
    ],
    "leftover_units": 1,
    "decimals": 0,
    "allocation": [
      {
        "part": 1,
        "ratio": "1",
        "exact_share": "1000/3",
        "share": "334",
        "extra_unit": true
      },
      {
        "part": 2,
        "ratio": "1",
        "exact_share": "1000/3",
        "share": "333",
        "extra_unit": false
      },
      {
        "part": 3,
        "ratio": "1",
        "exact_share": "1000/3",
        "share": "333",
        "extra_unit": false
      }
    ]
  },
  "exactness": {},
  "precision": null,
  "inputs": {
    "amount": "1000",
    "currency": "JPY",
    "parts": 3,
    "method": "largest_remainder",
    "rounding": "half_up"
  },
  "formula": "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)",
  "references": [
    {
      "title": "Dinero.js: allocate (10.03 split 50/50 gives 5.02 and 5.01; a ratio of 0 gets nothing)",
      "url": "https://www.dinerojs.com/api/mutations/allocate"
    },
    {
      "title": "Largest remainder method (Hamilton's method), with a worked example",
      "url": "https://en.wikipedia.org/wiki/Quota_method"
    },
    {
      "title": "ISO 4217 List One, current currencies and funds (SIX, the maintenance agency)",
      "url": "https://www.six-group.com/en/products-services/financial-information/market-reference-data/data-standards.html"
    },
    {
      "title": "ISO 4217 amendment 180: Bulgaria adopts the euro (1 January 2026)",
      "url": "https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/amendments/dl-currency-iso-amendment-180.pdf"
    }
  ],
  "warnings": []
}

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.

Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.