Skip to main content
Money on the Alvys Public API is an object, not a bare number:
Reading Amount and ignoring Currency works today for a single-currency tenant and breaks the moment one is not.

​
Currency is an ISO 4217 numeric code

Currency is an integer, not a string. It is the ISO 4217 numeric code, not the three-letter alphabetic one. A client that compares Currency against "USD" never matches. Map the numeric code to whatever your system uses at the boundary. Currency is nullable. A null means the tenant’s default currency — it does not mean “no currency” and it does not mean zero.

​
Amount and precision

Amount is a decimal number. Two rules matter when you send one:
  • Money carries at most 2 decimal places on the write surfaces that validate it. A third is refused rather than rounded, so the value that settles is always the value you sent. Round on your side, deliberately, before sending — do not rely on the API to do it for you.
  • Do not send a float you computed by dividing. 0.1 + 0.2 is the classic way to arrive at a value that fails a precision check for reasons that look absurd in a log. Compute in minor units, or in a decimal type, and format once at the edge.
Amounts are not minor units. 1250.75 is one thousand two hundred fifty dollars and seventy-five cents, not 1250.75 cents. If your system stores cents, divide before sending and multiply after reading.

​
Signs carry meaning

A negative amount is not an error, and it is not interchangeable with a positive one. The sign is how the API distinguishes money owed from money charged, and the rule differs by endpoint: Sending the wrong sign is refused rather than corrected. The endpoint will not flip it for you, because a flipped sign is money moving the opposite direction and the API cannot know which one you meant. Zero is refused on the surfaces where a zero-value record moves no money. Driver credits are the exception — a zero credit is allowed, because a statement line that shows an item moving no money is sometimes the point.

​
Reading money back

Every money field you read has the same shape, including inside collections and totals. When you compare an amount you sent against one you read back, compare Amount and Currency — a value that matches numerically in a different currency is not the same money.