> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alvys.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Currency and Money Fields

> How the Alvys Public API represents money — the Amount and Currency pair, the ISO 4217 numeric code, decimal precision, and how signs carry meaning.

Money on the Alvys Public API is an object, not a bare number:

```json theme={null}
{
  "Amount": 1250.75,
  "Currency": 840
}
```

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.

| Currency        | Numeric (what the API sends) | Alphabetic (what it is **not**) |
| --------------- | ---------------------------- | ------------------------------- |
| US dollar       | `840`                        | `USD`                           |
| Canadian dollar | `124`                        | `CAD`                           |
| Mexican peso    | `484`                        | `MXN`                           |

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.

<Note>
  **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.
</Note>

## 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:

| Surface                      | Sign                                                                |
| ---------------------------- | ------------------------------------------------------------------- |
| Accessorial charges          | `Rate` greater than zero                                            |
| Customer and carrier credits | `Rate` less than zero — the signed amount, not a positive magnitude |
| Driver credits               | `Amount` zero or positive — the magnitude                           |
| Deductions                   | Taken through the deductions surface, not as a negative credit      |

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.