Fiscal Years

Preview the year-end FX revaluation

Double-entry profiles only (403 DOUBLE_ENTRY_REQUIRED). Values every foreign-currency (FW) bank account and every open FW invoice, credit note, expense and revenue at the closing rate (Stichtagskurs) of the fiscal-year end and returns the CHF difference per item. Books nothing. Closing rates are prefilled (ESTV ICTax year-end list for a 31.12. close where it lists the currency, else the ESTV/BAZG daily rate of the closing date) and can be overridden in rates. Errors (400): FX_REVALUATION_TOO_EARLY (the year has not ended, with endDate), FX_REVALUATION_INVALID (policy / threshold), FX_INVALID_RATE (with currency), FX_PRIOR_YEAR_NOT_CLOSED (the previous fiscal year is still open, so this year holds no Saldovortrag and its FW saldi would be wrong: close the prior year first). The response carries a previewToken for the commit. Being a POST, it needs a read_write API key.

post/fiscal-years/{id}/fx-revaluation/preview

Request

  • Base URL: https://api.lumabill.ch/v1
  • URL: https://api.lumabill.ch/v1/fiscal-years/{id}/fx-revaluation/preview
  • Auth: HTTP bearer

Request body

ratesobject

Closing rate per currency, keyed by currency code. Optional on the preview (overrides the prefilled rate); required on the commit, one for every currency in scope (the commit never fetches a rate).

policy'stichtag' | 'niederstwert'

stichtag books unrealized gains and losses at the closing rate; niederstwert books no unrealized gains on open items (FW bank accounts are always valued at the closing rate). Default: the profile's fxValuationPolicy.

thresholdnumber double

Items whose CHF difference is below this amount are skipped

previewTokenstring

Commit only: the previewToken of the preview the commit books. When bookings in scope changed since that preview, the commit answers 409 FX_REVALUATION_PREVIEW_CHANGED and writes nothing; run the preview again and commit with its new token.

Example request

{
  "rates": {
    "EUR": {
      "rate": 0.9312,
      "source": "ICTAX",
      "rateType": "closing",
      "rateDate": "2025-12-31",
      "retrievedAt": "2026-01-05T08:00:00.000Z"
    },
    "USD": 0.8
  }
}

Response

The valuation with its rates, items, totals and warnings

runDatestring date

The fiscal-year end

policy'stichtag' | 'niederstwert'
thresholdnumber double
unchangedboolean

The current run already books exactly this result; a commit changes nothing

canCommitboolean
previewTokenstring

Identity of this preview (the ledger state it valued). Send it back on the commit; a commit whose token no longer matches the ledger answers 409 FX_REVALUATION_PREVIEW_CHANGED.

Example response

{
  "fiscalYear": {
    "year": 2025
  },
  "rates": [
    {
      "currency": "CHF",
      "source": "BAZG"
    }
  ],
  "items": [
    {
      "key": "bank:0d6f2c1e-...",
      "currency": "CHF"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.