Money
Handle amounts of money as exact decimals, with the number of decimals of each ISO 4217 currency: round, format, add, convert with a given rate, split without losing a cent, and convert to and from minor units. Typical uses: split an invoice into installments, send an amount in cents to a payment API.
money roundmoney roundmoney formatmoney formatmoney convertmoney convertmoney allocatemoney allocatemoney summoney summoney to_minormoney from_minormoney currency
money round <amount> <currency>
Description
Round an amount to the decimals of its currency, half up. Returns the amount with exactly these decimals
Round an amount to the decimals of its currency, half up. Returns the amount with exactly these decimals
Parameters
amount: The amount, with a point - String - required
currency: The ISO 4217 code, ex: EUR - String - required
amount: The amount, with a point - String - required
currency: The ISO 4217 code, ex: EUR - String - required
admin
money round "19.995" "EUR"
mentdb
20.00
yen have no decimals
admin
money round "1234.5" "JPY"
mentdb
1235
Kuwaiti dinars have 3
admin
money round "1.2345" "KWD"
mentdb
1.235
a decimal comma is refused
admin
money round "12,30" "EUR"
mentdb
ERROR: Sorry, an error appears (the parameter 'amount' must be a decimal number with a point, ex: 1234.50 (here '12,30')).
money round <amount> <currency> <params>
Description
Round with parameters: mode (half_up, half_even, half_down, up, down, ceiling, floor, exact), scale (the decimals, instead of those of the currency), increment (a cash step, ex: 0.05)
Round with parameters: mode (half_up, half_even, half_down, up, down, ceiling, floor, exact), scale (the decimals, instead of those of the currency), increment (a cash step, ex: 0.05)
Parameters
amount: The amount - String - required
currency: The ISO 4217 code - String - required
params: The parameters as JSON - String - required
amount: The amount - String - required
currency: The ISO 4217 code - String - required
params: The parameters as JSON - String - required
admin
money round "2.665" "EUR" "{\"mode\": \"half_even\"}"
mentdb
2.66
Swiss cash: steps of 5 centimes
admin
money round "12.37" "CHF" "{\"increment\": \"0.05\"}"
mentdb
12.35
exact: an error rather than a silent rounding
admin
money round "10.005" "EUR" "{\"mode\": \"exact\"}"
mentdb
ERROR: Sorry, an error appears (the amount 10.005 needs rounding to 2 decimals and the mode is exact).
money format <amount> <currency>
Description
Format an amount for people, in en-US
Format an amount for people, in en-US
Parameters
amount: The amount - String - required
currency: The ISO 4217 code - String - required
amount: The amount - String - required
currency: The ISO 4217 code - String - required
admin
money format "-1234.5" "USD"
mentdb
-$1,234.50
money format <amount> <currency> <params>
Description
Format with parameters: locale (a language tag: fr-FR, de-DE, de-CH, en-GB, ja-JP...), display (symbol, code or none), mode, scale, increment, grouping (false: no thousands separator), plain_spaces (true: ordinary spaces instead of the no-break spaces)
Format with parameters: locale (a language tag: fr-FR, de-DE, de-CH, en-GB, ja-JP...), display (symbol, code or none), mode, scale, increment, grouping (false: no thousands separator), plain_spaces (true: ordinary spaces instead of the no-break spaces)
Parameters
amount: The amount - String - required
currency: The ISO 4217 code - String - required
params: The parameters as JSON - String - required
amount: The amount - String - required
currency: The ISO 4217 code - String - required
params: The parameters as JSON - String - required
admin
money format "1234567.891" "EUR" "{\"locale\": \"fr-FR\"}"
mentdb
1 234 567,89 €
German, with the code
admin
money format "1234.5" "EUR" "{\"locale\": \"de-DE\", \"display\": \"code\"}"
mentdb
1.234,50 EUR
Swiss German
admin
money format "1234.5" "CHF" "{\"locale\": \"de-CH\"}"
mentdb
CHF 1’234.50
only the number, for a column of a table
admin
money format "1234.5" "EUR" "{\"locale\": \"fr-FR\", \"display\": \"none\", \"plain_spaces\": true}"
mentdb
1 234,50
Used in use cases (1 recipe)
Accountant & manager › Spread a global discount over the lines of an invoice without losing a cent
Accountant & manager › Spread a global discount over the lines of an invoice without losing a cent
money convert <amount> <from> <to> <rate>
Description
Convert with a rate given by the caller (1 unit of from = rate units of to), rounded half up to the decimals of the target currency
Convert with a rate given by the caller (1 unit of from = rate units of to), rounded half up to the decimals of the target currency
Parameters
amount: The amount - String - required
from: The source currency - String - required
to: The target currency - String - required
rate: The rate - String - required
amount: The amount - String - required
from: The source currency - String - required
to: The target currency - String - required
rate: The rate - String - required
admin
money convert "100" "EUR" "USD" "1.0834"
mentdb
108.34
euros to yen
admin
money convert "100" "EUR" "JPY" "162.4567"
mentdb
16246
money convert <amount> <from> <to> <rate> <params>
Description
Convert with parameters: inverse (true: the rate is 1 unit of to = rate units of from, as the ECB publishes it for EUR; the exact quotient is rounded once, so mode exact and the half modes are always right), mode, scale, increment
Convert with parameters: inverse (true: the rate is 1 unit of to = rate units of from, as the ECB publishes it for EUR; the exact quotient is rounded once, so mode exact and the half modes are always right), mode, scale, increment
Parameters
amount: The amount - String - required
from: The source currency - String - required
to: The target currency - String - required
rate: The rate - String - required
params: The parameters as JSON - String - required
amount: The amount - String - required
from: The source currency - String - required
to: The target currency - String - required
rate: The rate - String - required
params: The parameters as JSON - String - required
admin
money convert "100" "USD" "EUR" "1.0834" "{\"inverse\": true}"
mentdb
92.30
money allocate <amount> <currency> <ratios>
Description
Split an amount without losing a cent. ratios: a number of equal parts, or a JSON array of ratios (any scale: [50, 30, 20] or [0.5, 0.3, 0.2]). Returns a JSON array of amounts
Split an amount without losing a cent. ratios: a number of equal parts, or a JSON array of ratios (any scale: [50, 30, 20] or [0.5, 0.3, 0.2]). Returns a JSON array of amounts
Parameters
amount: The amount - String - required
currency: The ISO 4217 code - String - required
ratios: A number of parts, or a JSON array of ratios - String - required
amount: The amount - String - required
currency: The ISO 4217 code - String - required
ratios: A number of parts, or a JSON array of ratios - String - required
admin
money allocate "100" "EUR" "3"
mentdb
["33.34", "33.33", "33.33"]
a discount of 10 euros on 3 lines, by their amounts
admin
money allocate "10.00" "EUR" "[129.90, 45.50, 9.99]"
mentdb
["7.01", "2.45", "0.54"]
a refund: negative amounts
admin
money allocate "-0.05" "EUR" "2"
mentdb
["-0.03", "-0.02"]
money allocate <amount> <currency> <ratios> <params>
Description
Split with the parameter scale (the decimals, for a currency without minor unit or a finer split)
Split with the parameter scale (the decimals, for a currency without minor unit or a finer split)
Parameters
amount: The amount - String - required
currency: The ISO 4217 code - String - required
ratios: A number of parts, or a JSON array of ratios - String - required
params: The parameters as JSON - String - required
amount: The amount - String - required
currency: The ISO 4217 code - String - required
ratios: A number of parts, or a JSON array of ratios - String - required
params: The parameters as JSON - String - required
admin
money allocate "100" "XAU" "3" "{\"scale\": 3}"
mentdb
["33.334", "33.333", "33.333"]
Used in use cases (1 recipe)
Accountant & manager › Spread a global discount over the lines of an invoice without losing a cent
Accountant & manager › Spread a global discount over the lines of an invoice without losing a cent
money sum <amounts>
Description
Add amounts of one currency: "12.50 EUR", "EUR 12.50" or {"amount": ..., "currency": ...}. Returns {amount, currency, count}. Two currencies, or an amount with more decimals than its currency, are an error
Add amounts of one currency: "12.50 EUR", "EUR 12.50" or {"amount": ..., "currency": ...}. Returns {amount, currency, count}. Two currencies, or an amount with more decimals than its currency, are an error
Parameters
amounts: A JSON array of amounts - String - required
amounts: A JSON array of amounts - String - required
admin
money sum "[\"12.50 EUR\", \"EUR 3.10\", {\"amount\": \"0.40\", \"currency\": \"EUR\"}]"
mentdb
{"amount": "16.00", "currency": "EUR", "count": 3}
two currencies
admin
money sum "[\"12.50 EUR\", \"3 USD\"]"
mentdb
ERROR: Sorry, an error appears (the item 1 is in USD, not in EUR: convert it first with money convert).
money sum <amounts> <params>
Description
Add amounts with the parameter currency (for the amounts written without currency, and for an empty list)
Add amounts with the parameter currency (for the amounts written without currency, and for an empty list)
Parameters
amounts: A JSON array of amounts - String - required
params: The parameters as JSON - String - required
amounts: A JSON array of amounts - String - required
params: The parameters as JSON - String - required
admin
money sum "[0.1, 0.2]" "{\"currency\": \"EUR\"}"
mentdb
{"amount": "0.30", "currency": "EUR", "count": 2}
Used in use cases (1 recipe)
Accountant & manager › Spread a global discount over the lines of an invoice without losing a cent
Accountant & manager › Spread a global discount over the lines of an invoice without losing a cent
money to_minor <amount> <currency>
Description
The amount in minor units (cents), as payment APIs want it. An amount with more decimals is an error
The amount in minor units (cents), as payment APIs want it. An amount with more decimals is an error
Parameters
amount: The amount - String - required
currency: The ISO 4217 code - String - required
amount: The amount - String - required
currency: The ISO 4217 code - String - required
admin
money to_minor "19.90" "EUR"
mentdb
1990
yen have no minor unit
admin
money to_minor "1500" "JPY"
mentdb
1500
Used in use cases (1 recipe)
Accountant & manager › Spread a global discount over the lines of an invoice without losing a cent
Accountant & manager › Spread a global discount over the lines of an invoice without losing a cent
money from_minor <units> <currency>
Description
Minor units (cents) back to an amount
Minor units (cents) back to an amount
Parameters
units: An integer number of minor units - String - required
currency: The ISO 4217 code - String - required
units: An integer number of minor units - String - required
currency: The ISO 4217 code - String - required
admin
money from_minor "1990" "EUR"
mentdb
19.90
fils to Bahraini dinars (3 decimals)
admin
money from_minor "1990" "BHD"
mentdb
1.990
money currency <currency>
Description
The ISO 4217 data of a currency: {code, numeric_code, minor_units, name}. minor_units is null for a code without minor unit
The ISO 4217 data of a currency: {code, numeric_code, minor_units, name}. minor_units is null for a code without minor unit
Parameters
currency: The ISO 4217 code - String - required
currency: The ISO 4217 code - String - required
admin
money currency "EUR"
mentdb
{"code": "EUR", "numeric_code": "978", "minor_units": 2, "name": "Euro"}
the CFP franc of French Polynesia
admin
money currency "XPF"
mentdb
{"code": "XPF", "numeric_code": "953", "minor_units": 0, "name": "CFP Franc"}
an unknown code
admin
money currency "ABC"
mentdb
ERROR: Sorry, an error appears (the parameter 'currency': 'ABC' is not an ISO 4217 currency).
