Money

The Quarzo API represents each complete Money value with three fields:

json

{
  "amount": "10050",
  "currency": "EUR",
  "scale": 2
}

This value represents €100.50.

Fields

Field	Type	Description
`amount`	string	An integer amount in the smallest stored unit.
`currency`	string	A three-letter currency code, such as `EUR`.
`scale`	integer	The number of fractional digits in `amount`.

The API stores amount as text so that clients can preserve exact values. Do not convert a large amount to a JavaScript number.

The scale controls the number of fractional digits. Do not derive the scale from the currency.

For example, these values have the same currency and different scales:

json

{
  "amount": "10050",
  "currency": "EUR",
  "scale": 2
}

This value represents €100.50.

json

{
  "amount": "100500",
  "currency": "EUR",
  "scale": 3
}

This value represents €100.500.

Use this rule to read a Money value:

text

decimal value = amount / 10^scale

For amount = "10050" and scale = 2, the result is 100.50.

The stored scale is the source of truth. A currency can use a scale that differs from its usual minor-unit exponent.

When scale is 0, the amount has no fractional digits:

json

{
  "amount": "1200",
  "currency": "JPY",
  "scale": 0
}

This value represents ¥1,200.

Keep amount as text until you use an exact integer or decimal library.

When a client uses Moneta, convert the text to the library integer type and pass the stored scale.

When a client formats a value, use the stored scale for decimal placement.

Do not divide every amount by 100.

Do not use the currency code to select the scale.

Do not use floating-point arithmetic for Money values.

The following value is incomplete because it has no scale:

json

{
  "amount": "10050",
  "currency": "EUR"
}

The following value is incomplete because amount is not an integer string:

json

{
  "amount": "100.50",
  "currency": "EUR",
  "scale": 2
}

Use a complete value instead:

json

{
  "amount": "10050",
  "currency": "EUR",
  "scale": 2
}