# Minor Units Format (/guides/minor-units-format)



## Amount Format [#amount-format]

Acme maintains a consistent format for `amount` values across all Acme APIs.
All `amount` values provided in the API must be represented in their **smallest currency unit** as an integer.

The number of minor units per major unit follows the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard.

* Most currencies have 2 decimal places. `amount` is in cents, so multiply the major amount by 100.
* Some currencies have no minor unit (0 decimal places). `amount` equals the major amount.
* A small set of currencies have 3 decimal places. `amount` is in thousandths, so multiply the major amount by 1000.

### Examples [#examples]

| Currency | Decimal Places | Example Amount | Smallest Unit (ISO 4217 standard) | API Value |
| -------- | -------------- | -------------- | --------------------------------- | --------- |
| SGD      | 2              | $10.00         | cents                             | `1000`    |
| USD      | 2              | $10.00         | cents                             | `1000`    |
| EUR      | 2              | €10.00         | cents                             | `1000`    |
| JPY      | 0              | ¥10            | yen                               | `10`      |
| VND      | 0              | ₫10            | dong                              | `10`      |
| KWD      | 3              | KD 10.000      | fils                              | `10000`   |

### Currencies with no minor unit (0 decimal places) [#currencies-with-no-minor-unit-0-decimal-places]

For these currencies, send `amount` as the whole major amount. Do not multiply by 100.

For example, send `1000` for JPY ¥1,000.

| Code | Currency                  |
| ---- | ------------------------- |
| BIF  | Burundian Franc           |
| CLP  | Chilean Peso              |
| DJF  | Djiboutian Franc          |
| GNF  | Guinean Franc             |
| ISK  | Icelandic Króna           |
| JPY  | Japanese Yen              |
| KMF  | Comorian Franc            |
| KRW  | South Korean Won          |
| PYG  | Paraguayan Guaraní        |
| RWF  | Rwandan Franc             |
| UGX  | Ugandan Shilling          |
| VND  | Vietnamese Dong           |
| VUV  | Vanuatu Vatu              |
| XAF  | Central African CFA Franc |
| XOF  | West African CFA Franc    |
| XPF  | CFP Franc                 |

### Currencies with 3 decimal places [#currencies-with-3-decimal-places]

For these currencies, send `amount` in thousandths. Multiply the major amount by 1000.

For example, send `10500` for KWD 10.500.

| Code | Currency        |
| ---- | --------------- |
| BHD  | Bahraini Dinar  |
| IQD  | Iraqi Dinar     |
| JOD  | Jordanian Dinar |
| KWD  | Kuwaiti Dinar   |
| LYD  | Libyan Dinar    |
| OMR  | Omani Rial      |
| TND  | Tunisian Dinar  |

All other currencies use 2 decimal places. Send `amount` in cents by multiplying the major amount by 100.

### Decimal places follow the ISO 4217 scale [#decimal-places-follow-the-iso-4217-scale]

The number of decimal places is set by the ISO 4217 standard, not by the smallest physical coin or note in circulation.

For example, the smallest New Taiwan Dollar (TWD) coin is NT$1, but ISO 4217 assigns TWD 2 decimal places. So TWD is a 2 decimal place currency for the API.

* Send `1000` for NT$10.00.
* Send `1050` for NT$10.50.

### Important [#important]

* You must convert major currency units to the smallest unit before sending to Acme (e.g. send `1050` for SGD $10.50).
* All amounts will be returned in the smallest unit. Your system must convert these back to major units if needed for display.
* Amounts must not include decimal points. Submissions with decimal points (e.g. `10.50`) will be rejected.

```json
{
  "amount": 1050,
  "currency": "SGD"
}
```