Skip to content

Holiday pay debt ​

Holiday pay debt (lomapalkkavelka) is what an employer owes for holiday days earned but not yet taken, plus holiday bonus (lomaraha), plus the employer contributions on both. Finnish employers normally book it monthly. If your integration feeds the customer's bookkeeping, you need this pull in addition to Accounting data. Examples use the test environment; see Environments for demo and production.

Holiday pay debt is a separate pullHoliday years stored in Salaxy feed a calculation that runs on each request and is never stored. It has two outputs: a report shape with totals per holiday year, and a ledger-posted shape posted through an accounting target. Both go to your books. A warning box below says that every other accounting data response always has an empty holiday pay debt field.Holiday yearsstored per employmentComputed on callnever storedReport shapetotals per yearLedger shapeposted to accountsYour bookspost each periodEvery other accounting responsecarries no holiday pay debt: the field is always empty, with no error
The debt has its own two endpoints. Nothing pushes it and no salary or invoice carries it.

Read this first ​

  • It is computed on request and never stored. There is no balance to read, no history and no id. Every call recomputes the figure from the stored holiday years.
  • It is never pushed. No webhook or status change announces it. Your system decides when to ask, usually once a month with the period accounting report.
  • No other response includes it. The monthly report, a fetch by calculation, a saved report and the payment channel pulls all have summary.holidayCalc set to null. The call succeeds and reports no debt at all, every month. If a company with employees shows no debt in your bookkeeping, check this first.

What the figure contains ​

Both endpoints return the same seven figures. Five are employer contributions, so the debt is larger than the accrued gross holiday pay.

FieldMeaning
totalAccruedHolidayPayAccrued holiday pay and holiday compensation
totalAccruedHolidayBonusAccrued holiday bonus (lomaraha)
totalAccruedHolidaySocialSecurityHealth insurance contribution on the above
totalAccruedHolidayPensionEmployee pension (TyEL) contribution
totalAccruedHolidayUnemploymentUnemployment insurance contribution
totalAccruedHolidayAccidentInsuranceAccident and occupational disease insurance
totalAccruedHolidayGroupLifeInsuranceGroup life insurance

The contributions come from the same calculation engine and rates as an actual salary.

Which fits you? ​

The endpoints differ in shape and in parameters. Choose by what you do with the result.

Report shape ​

Fits a system that displays or stores the figure, needs it per holiday year, or posts to its own chart of accounts.

Report shape: how it works
http
GET /v03/api/reports/holiday-pay-debt/2026-05-01 HTTP/1.1
Host: test-secure.salaxy.com
Authorization: Bearer <access token>

The only query parameter is employmentIds. The route is also available in v04 (/v04/api/reports/holiday-pay-debt/{refDate}).

json
{
  "officialId": "1234567-8",
  "employer": { "displayName": "Test Company Oy", "initials": "TC" },
  "period": { "start": "2025-06-01", "end": "2026-05-31" },
  "holidayCalc": {
    "totalAccruedHolidayPay": 4820.50,
    "totalAccruedHolidayBonus": 2410.25,
    "totalAccruedHolidaySocialSecurity": 133.98,
    "totalAccruedHolidayPension": 1266.53,
    "totalAccruedHolidayUnemployment": 39.77,
    "totalAccruedHolidayAccidentInsurance": 51.30,
    "totalAccruedHolidayGroupLifeInsurance": 4.61
  },
  "holidayYears": [
    {
      "holidayYear": { "year": 2025, "employmentId": "EMP123" },
      "holidayCalc": { "totalAccruedHolidayPay": 3110.00 }
    },
    {
      "holidayYear": { "year": 2026, "employmentId": "EMP123" },
      "holidayCalc": { "totalAccruedHolidayPay": 1710.50 }
    }
  ]
}

The top-level holidayCalc is the company total. Each entry in holidayYears repeats the seven fields for one holiday year of one employment, so a company with unheld holidays from several years appears several times. The sample shows one field per year for brevity.

Ledger-posted shape ​

Fits an import straight into bookkeeping, where Salaxy applies the chart of accounts.

Ledger-posted shape: how it works
http
GET /v03/api/reports/accounting/2026-05-01/holiday-pay-debt?target=default HTTP/1.1
Host: test-secure.salaxy.com
Authorization: Bearer <access token>

Query parameters: target (the accounting target), employmentIds, and fromHolidayYear (count debt only from that holiday year on). Only this endpoint takes target and fromHolidayYear. It is v03 only; on v04 use the report shape.

The response is an ordinary AccountingData object, split by cost-accounting dimension, with zero rows omitted. A shortened sample:

json
{
  "ledgerAccounts": [
    {
      "accountNumber": "5330",
      "accountName": "Lomapalkkojen jaksotus",
      "saldo": 7230.75,
      "entries": [
        { "entryDate": "2026-05-31", "description": "Kertyneet lomapalkat ja lomakorvaukset", "isDebit": true, "amount": 4820.50 },
        { "entryDate": "2026-05-31", "description": "Kertyneet lomarahat", "isDebit": true, "amount": 2410.25 }
      ]
    },
    {
      "accountNumber": "2962",
      "accountName": "Lomapalkkamenot (siirtovelat)",
      "saldo": -7230.75,
      "entries": [
        { "description": "Kertyneet lomapalkat ja lomakorvaukset", "isDebit": false, "amount": 4820.50 },
        { "description": "Kertyneet lomarahat", "isDebit": false, "amount": 2410.25 }
      ]
    }
  ],
  "officialId": "1234567-8",
  "summary": {
    "holidayCalc": {
      "totalAccruedHolidayPay": 4820.50,
      "totalAccruedHolidayBonus": 2410.25
    }
  }
}
  • Entries have no code. Holiday pay and holiday bonus post to the same account pair under the default chart, so only the Finnish description tells them apart.
  • The entries are an accrual pair, not a payable: debit to an accrual account (jaksotus), credit to a transfer debt account (siirtovelat). The contributions post the same way to a second account pair.
  • summary.holidayCalc always has all seven figures, even when the posted rows do not. Compare the two before you import.

Check what the target posts ​

Which rows appear depends on the ruleset of the accounting target, and a row the target does not post comes back with no account and no amount, not as an error.

  • Several standard targets ship with holiday accruals switched off. Under them the ledger shape returns no accrual rows. Accruals can be switched on in a copy of the target.
  • Accident insurance and group life never post under any standard target. The ledger shape therefore totals less than the report shape.

Treat the report shape as the authority for the total. Prefer it if you post to your own chart of accounts. To check a target, fetch it by id (GET /v03/api/accounting-target/{id}; the list endpoint has no ruleset). In ruleSet.rows, filter entryCodeGroup to totalType and read isIncluded on these five codes:

totalAccruedHolidayPay, totalAccruedHolidayBonus, totalAccruedHolidaySocialSecurity, totalAccruedHolidayPension, totalAccruedHolidayUnemployment.

A missing row behaves like isIncluded: false. Do not look for the other two by name: their codes are spelled without Holiday (totalAccruedAccidentInsurance, totalAccruedGroupLifeInsurance) and do not post under any standard target whatever isIncluded says. Get those two figures from the report shape.

Posting the debt each period ​

Every call returns a balance, not a movement. The figure is the whole liability as at refDate. Salaxy keeps no record of what you posted before, has no "changes since" parameter and never returns reversals. Importing month after month as is accumulates: 10 000 EUR in May and 10 500 EUR in June leave 20 500 EUR credited against a true liability of 10 500 EUR. Pick one pattern.

PatternHowNotes
Reversing entry (jaksotuksen purku)Post the full accrual at period end. Reverse the identical entry on the first day of the next period, then post the new full accrual.The usual Finnish practice for accrual accounts. Each import is independent, so a re-run is harmless. Recommended.
Delta postingLeave the accrual standing and post only the difference from the last posted figure.Fewer entries, but you must store the last posted amount per company. A missed or duplicated run corrupts the balance silently.

Reference date and rounding ​

  • refDate is the last month included. The period runs to the end of that month whatever day you pass: 2026-05-01, 2026-05-15 and 2026-05-31 all return the debt at 31 May 2026.
  • Remaining holiday is rounded up to whole days, so the debt is slightly conservative.
  • An over-drawn holiday year counts as zero, never negative.

Where the numbers come from ​

The debt is derived from holiday years, stored objects you can read and write.

MethodPathPurpose
GET, POST/v03/api/holidaysRead or save holiday years
POST/v03/api/holidays/employment/{employmentId}Create holiday years for an employment from a specification
GET/v03/api/holidays/employment/{employmentId}/available-holiday-accrualsRemaining holiday days
POST/v03/api/holidays/year/{year}/{employmentId}/holiday-pay/recalculateRecalculate after changing salary data
  • A holiday year (lomanmääräytymisvuosi) runs from 1 April to 31 March. The matching leave period is 2 May to 30 April of the next year.
  • Accrual is kept in days: an opening balance plus days accrued per month. Euro amounts come from separately calculated daily rates.
  • The daily rate depends on the holiday pay method of the year: normal monthly pay, average daily pay, average hourly pay, percentage or holiday compensation.
  • Missing or stale holiday years give a low figure, not an error. When you onboard a company, check that holiday years exist for the current and the previous holiday year before you trust the first report.
  • Migrating balances from another system: new holiday years arrive with estimated days in every past month. Overwrite each month's daysAccrued with the real figure and source: manual, and put only days carried over from earlier years in startSaldo, or the days count twice. For the monthly pay method the employment also needs a monthly salary default row, or the daily rate and the debt are zero.

When a figure looks wrong ​

The endpoints are read only. Most inputs are company settings that the customer or its accounting firm keeps in the Salaxy UI. The screens are in Finnish.

FieldDriven byCustomer checks
totalAccruedHolidayPaydaily rate times remaining daysholiday year of the employment
totalAccruedHolidayBonusthe lomaraha multiplier of the holiday yearholiday year of the employment
totalAccruedHolidaySocialSecuritystatutory ratenothing, not configurable
totalAccruedHolidayPensionthe company's pension (TyEL) contractAsetukset, Vakuutukset
totalAccruedHolidayUnemploymentstatutory rate and payroll size bandnothing in normal use
totalAccruedHolidayAccidentInsurancethe company's accident insurance percentageAsetukset, Vakuutukset
totalAccruedHolidayGroupLifeInsurancethe company's group life percentageAsetukset, Vakuutukset

Holiday pay calculation rules sit under Asetukset, Kirjanpitokohteet, in the Loma-asetukset card.

Accident insurance and group life are often zero. The other contributions fall back on statutory rates. These two are per-policy percentages that exist only on the company's own insurance contract. With no contract on file both are zero, with no error or warning. The percentage fields are hidden until an insurance company is selected on the Tapaturmavakuutus card.

Correcting a percentage fixes past holiday years, because the debt is recomputed on every call. It does not change payroll already run: those calculations keep their old rates, so the debt report and old payslips then differ.

Test it ​

  1. Create a test employee and employment (Employees and employments) and check that holiday years exist: GET /v03/api/holidays.
  2. Call the report shape with a date in the current month. Expect 200 and the seven fields.
  3. Call the ledger shape with target=default. Compare the sum of the rows with summary.holidayCalc. A gap of the accident and group life figures is expected.
  4. For more on test data, see Test endpoints and test data.

Checklist ​

  • Call a debt endpoint once per period. Never read the debt from other accounting responses.
  • Choose reversing entries or delta posting and apply it to every company.
  • Reconcile the ledger shape with the report shape against the target you will really use.
  • Verify that holiday years exist for new companies before you trust the first figure.
  • Treat zero accident and group life figures as a missing insurance contract before you suspect an error.

Next: Monthly cycle

Every page is also available as Markdown: add .md to its URL — a folder page such as white-label/ is white-label/index.md. Index for LLMs: llms.txt. Questions: Support.