Money & decimals

Getting money right is the whole point of an accounting API, so the rules are strict and consistent.

Money is always a string

Every monetary amount is serialised as a JSON string with a fixed two decimals:

{ "subtotal": "1033.06", "btw_total": "216.94", "total": "1250.00" }

Never a float (1250.0 loses cents to binary rounding) and never an integer count of cents. Parse these into your language's exact decimal type (BigDecimal, decimal, Money), not a float.

• null means "no amount", which is distinct from "0.00" (an amount that happens to be zero).
• Invoice and quote totals are always positive — direction is carried by the is_credit_note flag, not a minus sign.
• A bank transaction amount is signed: negative for money out, positive for money in.

Decimal fields are strings too

Non-money decimal-cast values — quantities, tax rates, hours — are also strings, for the same exactness reason:

{ "quantity": "2.50", "btw_percentage": "21.00", "hours": "7.75" }

Writing money and decimals

On the way in, send a plain dot-decimal string:

• Use a dot for the decimal separator: "1250.00". A comma is rejected — "1250,00" is a validation error, even though Dutch UIs display it that way.
• No thousands separators, no currency symbol, no exponent: not "1.250,00", not "€1250", not "1.25e3".
• A native JSON number (1250.00) is also accepted on write, but a string is recommended so your own serialiser never turns it back into a lossy float.

Ceilings apply: a money value tops out at an absolute 99999999.99, and a non-money decimal at 9999999.9999.

{
  "amount": "49.99",
  "vat_rate": "21",
  "items": [
    { "description": "Consulting", "quantity": "10", "unit_price": "103.31", "btw_percentage": 21 }
  ]
}