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

# Currencies

## Currency Amount Formatting

**Amount values are always provided in the currency's smallest unit.**

The format depends on the currency's decimal structure:

• **For most currencies (exponent = 2):**
– Currencies: USD, CAD, EUR, GBP, etc.
– Enter amounts in cents/pence (smallest fractional unit)
– Example: "1000" → \$10.00 USD, €10.00 EUR, £10.00 GBP

• **Exception – no fractional unit (exponent = 0):**
– Currencies: CLP, JPY, KRW, VND
– Enter amounts as whole units (not divided by 100)
– Example: "1000" → ¥1000 JPY, ₩1000 KRW (not divided)

This ensures accurate processing and representation across all currencies, especially with respect to rounding.

When creating a calculation for a product that costs \$10.00 USD, you'd report that value as `1000` cents in the `amount` field. For a product that costs ¥1000 JPY, you'd report that value as `1000` in the `amount` field.

```json theme={null}
    "line_items": [
      {
        "reference_line_item_id": "line_123456789",
        "reference_product_id": "p-1233543",
        "amount": 1000,
        "quantity": 1
      }
    ]
```

In the same way, tax and accounting values returned are also in the currency's smallest unit (e.g., if USD then this is returned in cents where 2000 = \$20.00).

The below response is for a `calculation` on a \$2.00 USD item with a 7% tax rate. This leads to 14 cents in tax.

```json theme={null}
{
  "calculation_id": "calc_17364047950082c1fd8f0-f763-40f8-8c02-e8fc9ded0944",
  "object": "tax.calculation",
  "line_items": [
    {
      "line_item_id": "line_987654321",
      "reference_product_id": "temp-a4a427d4-42fc-47f1-9092-c74f935438a3",
      "reference_product_name": "temp-a4a427d4-42fc-47f1-9092-c74f935438a3",
      "product_tax_code": "GENERAL_MERCHANDISE",
      "tax_included_in_amount": false,
      "tax_jurisdictions": [
        {
          "tax_rate": 0.07,
          "rate_type": "REDUCED_RATE",
          "jurisdiction_name": "State"
        }
      ],
      "tax_amount": 14,
      "amount_excluding_tax": 200,
      "amount_including_tax": 214
    }
  ],
  "total_tax_amount": 14,
  "total_amount_excluding_tax": 200,
  "expires_at": 1714787673,
  "testmode": "false"
}
```

## Supported Currencies by API Version

The supported currencies depend on which API version you're using:

### 2025-05-12 - 32 Currencies

The API version 2025-05-12 supports all currencies from the previous version **plus** 22 additional currencies for a total of 32:

#### Original 10 Currencies (from 2024-09-01)

| Currency Code | Currency Name        |
| ------------- | -------------------- |
| BGN           | Bulgarian Lev        |
| CAD           | Canadian Dollar      |
| CZK           | Czech Koruna         |
| DKK           | Danish Krone         |
| EUR           | Euro                 |
| HUF           | Hungarian Forint     |
| PLN           | Polish Złoty         |
| RON           | Romanian Leu         |
| SEK           | Swedish Krona        |
| USD           | United States Dollar |

#### Additional 22 Currencies (new in 2025-05-12)

| Currency Code | Currency Name               |
| ------------- | --------------------------- |
| AED           | United Arab Emirates Dirham |
| ARS           | Argentine Peso              |
| AUD           | Australian Dollar           |
| CHF           | Swiss Franc                 |
| CLP           | Chilean Peso                |
| EGP           | Egyptian Pound              |
| GBP           | British Pound               |
| HKD           | Hong Kong Dollar            |
| IDR           | Indonesian Rupiah           |
| ILS           | Israeli New Shekel          |
| INR           | Indian Rupee                |
| JPY           | Japanese Yen                |
| KRW           | South Korean Won            |
| MOP           | Macanese Pataca             |
| NOK           | Norwegian Krone             |
| NZD           | New Zealand Dollar          |
| PHP           | Philippine Peso             |
| SAR           | Saudi Riyal                 |
| SGD           | Singapore Dollar            |
| THB           | Thai Baht                   |
| TRY           | Turkish Lira                |
| VND           | Vietnamese Dong             |

## How to Specify Currency

When creating calculations, specify the currency in the `customer_currency_code` field:

<Tabs group="api-version">
  <Tab title="2025-05-12">
    ```json theme={null}
    {
      "order_details": {
        "customer_currency_code": "GBP",
        "tax_included_in_amount": false,
        "automatic_tax": "auto",
        "line_items": [...]
      }
    }
    ```
  </Tab>

  <Tab title="2024-09-01">
    ```json theme={null}
    {
      "order_details": {
        "customer_currency_code": "USD",
        "tax_included_in_amount": false,
        "line_items": [...]
      }
    }
    ```
  </Tab>
</Tabs>

## Exchange Rates

Once per day, we will reconcile all `transactions` that were created in the last 24 hours, and record the exchange rate(s) for that day.
This allows us to present a single report in your functional currency on your dashboard, even if you are collecting and filing tax across multiple countries.