Exchange rates

ECB rates against the entity's currency, cross rates, history, a converter, the official VAT rates next to them, and the foreign-currency exposure a revaluation would remeasure. Reference data only: nothing here changes the books.

GET /v1/entities/{entity}/fx/convert

Convert an amount at the ECB rate

The amount in the other currency at the ECB rate of the fixing on or before the date, with the rate, its inverse, the route and the fixing day used.

converted is amount times the 10-decimal rate, rounded half-even to the minor unit of the target currency, as data-vNext's /v1/fx/convert rounds. The result is indicative: the books round half-up, so a booked amount can differ by one minor unit on an exact tie. It uses the ECB rate the books use, not the official VAT rate (/tax-rates). 422 for a currency the ECB does not publish or an amount with more than 18 integer digits; 404 if there is no fixing within 7 days before the date.

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/fx/convert?amount=1250.50&from=USD&to=CHF" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "entity": "string",
  "requested_date": "2026-09-21",
  "fixing_date": "2026-09-21",
  "fallback": true,
  "source": "string",
  "sources": [
    {
      "authority": "string",
      "url": "string",
      "reference": "string"
    }
  ],
  "dataset_version": "string",
  "decimals": 1,
  "rounding": "string",
  "amount": "string",
  "from_currency": "string",
  "to_currency": "string",
  "rate": "string",
  "inverse": "string",
  "converted": "string",
  "path": [
    "string"
  ]
}

GET /v1/entities/{entity}/fx/exposure

Get the foreign-currency exposure

Open receivables, open payables and foreign-currency bank balances by currency, in the transaction currency and in the functional currency at the date's rate, against the amount booked: difference is how far each balance moves if revalued, and unrealised the result (gain positive) the period-end FX revaluation would post.

It uses the revaluation's own selection, so at a period end totals.unrealised is the revaluation's balancing line: posted documents in another currency than the functional one, open at the date (payments and credit notes posted on or before it), and the balances of foreign-currency asset accounts; each value rounded half up to the minor unit. Credit notes count negative. Each figure's count is the number of rows /exposure/items lists for it.

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/fx/exposure" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "entity": "string",
  "requested_date": "2026-09-21",
  "fixing_date": "2026-09-21",
  "fallback": true,
  "source": "string",
  "sources": [
    {
      "authority": "string",
      "url": "string",
      "reference": "string"
    }
  ],
  "dataset_version": "string",
  "decimals": 1,
  "rounding": "string",
  "functional_currency": "string",
  "rows": [
    {
      "currency": "string",
      "rate": "string",
      "receivables": {
        "count": null,
        "booked": null,
        "revalued": null,
        "difference": null,
        "amount": null
      },
      "payables": {
        "count": null,
        "booked": null,
        "revalued": null,
        "difference": null,
        "amount": null
      },
      "bank": {
        "count": null,
        "booked": null,
        "revalued": null,
        "difference": null,
        "amount": null
      },
      "unrealised": "string"
    }
  ],
  "totals": {
    "receivables": {
      "count": 1,
      "booked": "string",
      "revalued": "string",
      "difference": "string"
    },
    "payables": {
      "count": 1,
      "booked": "string",
      "revalued": "string",
      "difference": "string"
    },
    "bank": {
      "count": 1,
      "booked": "string",
      "revalued": "string",
      "difference": "string"
    },
    "unrealised": "string"
  }
}

GET /v1/entities/{entity}/fx/exposure/items

List the positions behind the exposure

The open documents and bank balances that make up /exposure, with the amount in the transaction currency, the booked amount, the value at the date's rate and the difference. total is the number of matching positions and equals the count of the matching cells of /exposure; a credit note is negative. Ordered by currency, side and number or code.

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/fx/exposure/items" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "entity": "string",
  "requested_date": "2026-09-21",
  "fixing_date": "2026-09-21",
  "side": "bank",
  "currency": "string",
  "total": 1,
  "limit": 1,
  "offset": 1,
  "items": [
    {
      "side": "bank",
      "currency": "string",
      "kind": "account",
      "reference": "string",
      "description": "string",
      "document_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "account_code": "string",
      "document_date": "2026-09-21",
      "amount": "string",
      "booked": "string",
      "revalued": "string",
      "difference": "string"
    }
  ]
}

GET /v1/entities/{entity}/fx/history

Get the rate history of a currency pair

The daily ECB cross rate of a pair over a range, for a chart and a table: every fixing day's rate (weekends and holidays have none), the first and last rate, the minimum and maximum with the day each occurred, the average and the change.

The average is the arithmetic mean of the daily cross rates, rounded to 10 decimals half-even: the method of the IAS 21 average, applied to the range. month adds the IAS 21 average and closing rate of the latest completed month in the range, from data-vNext's /v1/fx/period-rates: the closing rate is the one the period-end revaluation uses. 422 for a currency the ECB does not publish, equal currencies, a reversed range or one over 1830 days; 404 if the range has no fixing of both currencies.

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/fx/history?base=USD&quote=CHF" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "entity": "string",
  "base": "string",
  "quote": "string",
  "start": "2026-09-21",
  "end": "2026-09-21",
  "source": "string",
  "sources": [
    {
      "authority": "string",
      "url": "string",
      "reference": "string"
    }
  ],
  "dataset_version": "string",
  "decimals": 1,
  "rounding": "string",
  "points": [
    {
      "date": "2026-09-21",
      "rate": "string"
    }
  ],
  "count": 1,
  "first": {
    "date": "2026-09-21",
    "rate": "string"
  },
  "last": {
    "date": "2026-09-21",
    "rate": "string"
  },
  "minimum": {
    "date": "2026-09-21",
    "rate": "string"
  },
  "maximum": {
    "date": "2026-09-21",
    "rate": "string"
  },
  "average": "string",
  "change": "string",
  "change_percent": "string",
  "month": {
    "period": "string",
    "average": "string",
    "closing": "string",
    "fixings": 1,
    "first_fixing": "2026-09-21",
    "last_fixing": "2026-09-21"
  }
}

GET /v1/entities/{entity}/fx/matrix

Get the cross-rate matrix of a set of currencies

The cross rate of every currency pair of a set. Read it as 1 row = x column: rows[i].rates[j] is the units of currencies[j] one currencies[i] buys, and the diagonal is 1.

Each cell is the ECB rate of the column currency divided by that of the row currency (triangulated through EUR, method), computed at full precision and rounded once to 10 decimals half-even; the inverse cell is computed the same way round, not as 1 over the rounded rate, so a pair and its inverse differ from 1 by at most the rounding of 10 decimals. 422 for a currency the ECB does not publish or more than 24 currencies; 404 if there is no fixing within 7 days before the date.

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/fx/matrix" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "entity": "string",
  "requested_date": "2026-09-21",
  "fixing_date": "2026-09-21",
  "fallback": true,
  "source": "string",
  "sources": [
    {
      "authority": "string",
      "url": "string",
      "reference": "string"
    }
  ],
  "dataset_version": "string",
  "decimals": 1,
  "rounding": "string",
  "reading": "string",
  "method": "string",
  "currencies": [
    "string"
  ],
  "rows": [
    {
      "currency": "string",
      "rates": [
        "string"
      ]
    }
  ]
}

GET /v1/entities/{entity}/fx/rates

List exchange rates against the entity's currency

Every currency the ECB publishes against the entity's functional currency: the rate (1 currency = rate functional), its inverse, the fixing day used, and whether the entity uses the currency (documents, active bank accounts, open items; those first).

Rates are the ECB euro reference rates of the fixing, triangulated through EUR and rounded once to 10 decimals half-even (decimals, rounding), so they equal data-vNext's /v1/fx/convert. fixing_date is the ECB day used, fallback is true when it is earlier than requested_date, and sources names the authority. 404 if there is no fixing within 7 days before the date; 422 if the functional currency is not an ECB currency.

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/fx/rates" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "entity": "string",
  "requested_date": "2026-09-21",
  "fixing_date": "2026-09-21",
  "fallback": true,
  "source": "string",
  "sources": [
    {
      "authority": "string",
      "url": "string",
      "reference": "string"
    }
  ],
  "dataset_version": "string",
  "decimals": 1,
  "rounding": "string",
  "functional_currency": "string",
  "rows": [
    {
      "currency": "string",
      "rate": "string",
      "inverse": "string",
      "in_use": true,
      "documents": 1,
      "bank_accounts": 1,
      "open_items": 1
    }
  ],
  "in_use": 1
}

GET /v1/entities/{entity}/fx/tax-rates

Compare accounting rates with the official VAT rates

For the entity's country, side by side: the accounting rate (the ECB rate the books translate documents, payments and revaluations at, for bookkeeping) and the official VAT rate (BAZG for Switzerland, MWSTV Art. 45; the monthly rates the BMF announces for Germany, derived from the ECB reference rates and read from the Bundesbank, UStG §16 Abs. 6; the rate for the VAT amounts and turnover on the return), both as tax currency per one unit of the foreign currency, with the difference.

The VAT rate follows the method of the entity's VAT settings (tax.method). A rate that is not published yet, or does not list the currency, is provisional with the reason. Where the country prescribes no official rate, or the entity does not book in its tax currency, supported is false and rows is empty. 404 if there is no ECB fixing within 7 days.

Parameters

Example request

curl "$ERP_URL/v1/entities/CH01/fx/tax-rates" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Example response (shape)

{
  "entity": "string",
  "jurisdiction": "string",
  "functional_currency": "string",
  "requested_date": "2026-09-21",
  "supported": true,
  "tax_currency": "string",
  "accounting": {
    "series": "string",
    "use": "string",
    "fixing_date": "2026-09-21",
    "sources": [
      {
        "authority": null,
        "url": null,
        "reference": null
      }
    ]
  },
  "tax": {
    "method": "string",
    "series": "string",
    "use": "string",
    "legal_basis": "string",
    "authority": {
      "authority": null,
      "url": null,
      "reference": null
    }
  },
  "dataset_version": "string",
  "rows": [
    {
      "currency": "string",
      "in_use": true,
      "accounting_rate": "string",
      "status": "final",
      "tax_rate": "string",
      "published_rate": "string",
      "quoted_as": "string",
      "tax_period": "string",
      "tax_fixing_date": "2026-09-21",
      "difference": "string",
      "difference_percent": "string",
      "reason": "string"
    }
  ]
}

Schemas

FxAccountingBasis

FxConversion

FxExposure

FxExposureCell

FxExposureItem

FxExposureItems

FxExposureRow

FxExposureTotals

FxExtreme

FxHistory

FxMatrix

FxMatrixRow

FxMonthAverage

The IAS 21 rates of a completed calendar month, from data-vNext /v1/fx/period-rates: the average revaluation-style reports use for income and expenses and the closing rate the revaluation uses for balances.

FxPoint

FxRateRow

FxRates

FxSourceRef

Where a rate comes from: the authority behind it and the page that publishes it.

FxSubtotal

FxTaxBasis

FxTaxRateRow

FxTaxRates