Exchange Rates

An exchange rate tells you how many units of one currency equal one unit of another on a given date. Numeral uses daily rates to report transactions collected in different currencies in a single currency.Supported currencies are the same as customer_currency_code on calculations. See Currencies.The endpoint works with any X-API-Version, or none.

Endpoints

Retrieve an exchange rateGET/tax/exchange_rates

The Exchange rate object

Attributes

string, value is "tax.exchange_rate"

String representing the object’s type.

string

The date of the rate, YYYY-MM-DD (UTC).

string

ISO 4217 code of the currency converted from, in uppercase.

string

ISO 4217 code of the currency converted to, in uppercase.

number

Units of target_currency per 1 unit of base_currency. Not rounded. 1 when both currencies are the same.

For weekends and market holidays, the rate is from the most recent trading day.

The Exchange rate object

{
  "object": "tax.exchange_rate",
  "date": "2026-10-01",
  "base_currency": "USD",
  "target_currency": "EUR",
  "rate": 0.88898
}

Retrieve an exchange rate

Returns the rate between two currencies on a date. Try it in the API reference.

Parameters

string

required

The date, YYYY-MM-DD (UTC). Can’t be later than today in UTC.

string

required

ISO 4217 code of the currency to convert from, e.g. USD. Case-insensitive.

string

required

ISO 4217 code of the currency to convert to, e.g. EUR. Case-insensitive.

Any other query parameter returns UNRECOGNIZED_FIELD.

Returns

An Exchange rate object. Currency codes come back in uppercase, whatever case you sent.

GET /tax/exchange_rates

curl 'https://api.numeralhq.com/tax/exchange_rates?date=2026-10-01&base_currency=USD&target_currency=EUR' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'

Response

{
  "object": "tax.exchange_rate",
  "date": "2026-10-01",
  "base_currency": "USD",
  "target_currency": "EUR",
  "rate": 0.88898
}

Lowercase codes

curl 'https://api.numeralhq.com/tax/exchange_rates?date=2026-10-01&base_currency=usd&target_currency=gbp' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-API-Version: 2026-11-01'

Lowercase response

{
  "object": "tax.exchange_rate",
  "date": "2026-10-01",
  "base_currency": "USD",
  "target_currency": "GBP",
  "rate": 0.757736
}

Errors

Errors return code, type, and message. Handle them by type. Full list in Error Codes.Checks run in the order below. If a request has more than one error, only the first is returned.

HTTP	`type`	When
400	`UNRECOGNIZED_FIELD`	A query parameter other than `date`, `base_currency`, or `target_currency` was sent.
400	`MISSING_FIELD`	A required query parameter is missing or empty.
400	`INVALID_DATE`	`date` isn’t a valid calendar date in `YYYY-MM-DD` format.
400	`DATE_OUT_OF_RANGE`	`date` is later than today in UTC.
400	`INVALID_CURRENCY_CODE`	`base_currency` or `target_currency` isn’t a three-letter code.
400	`UNSUPPORTED_CURRENCY_CODE`	`base_currency` or `target_currency` isn’t a supported currency.
404	`EXCHANGE_RATE_NOT_FOUND`	No rate is available for the currency pair on that date.

{
  "code": 400,
  "type": "DATE_OUT_OF_RANGE",
  "message": "date 2099-01-01 is in the future. Latest available date is 2026-10-26 (today, UTC)."
}

{
  "code": 400,
  "type": "UNSUPPORTED_CURRENCY_CODE",
  "message": "target_currency \"ZZZ\" is not supported."
}

Getting Started

API Reference

The Exchange rate object

Attributes

Retrieve an exchange rate

Parameters

Returns

Errors

​The Exchange rate object

​Attributes

​Retrieve an exchange rate

​Parameters

​Returns

​Errors

The Exchange rate object

Attributes

Retrieve an exchange rate

Parameters

Returns

Errors