Appearance
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.
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.holidayCalcset tonull. 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.
| Field | Meaning |
|---|---|
totalAccruedHolidayPay | Accrued holiday pay and holiday compensation |
totalAccruedHolidayBonus | Accrued holiday bonus (lomaraha) |
totalAccruedHolidaySocialSecurity | Health insurance contribution on the above |
totalAccruedHolidayPension | Employee pension (TyEL) contribution |
totalAccruedHolidayUnemployment | Unemployment insurance contribution |
totalAccruedHolidayAccidentInsurance | Accident and occupational disease insurance |
totalAccruedHolidayGroupLifeInsurance | Group 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
descriptiontells 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.holidayCalcalways 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.
| Pattern | How | Notes |
|---|---|---|
| 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 posting | Leave 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
refDateis the last month included. The period runs to the end of that month whatever day you pass:2026-05-01,2026-05-15and2026-05-31all 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.
| Method | Path | Purpose |
|---|---|---|
| GET, POST | /v03/api/holidays | Read 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-accruals | Remaining holiday days |
| POST | /v03/api/holidays/year/{year}/{employmentId}/holiday-pay/recalculate | Recalculate 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
daysAccruedwith the real figure andsource: manual, and put only days carried over from earlier years instartSaldo, 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.
| Field | Driven by | Customer checks |
|---|---|---|
totalAccruedHolidayPay | daily rate times remaining days | holiday year of the employment |
totalAccruedHolidayBonus | the lomaraha multiplier of the holiday year | holiday year of the employment |
totalAccruedHolidaySocialSecurity | statutory rate | nothing, not configurable |
totalAccruedHolidayPension | the company's pension (TyEL) contract | Asetukset, Vakuutukset |
totalAccruedHolidayUnemployment | statutory rate and payroll size band | nothing in normal use |
totalAccruedHolidayAccidentInsurance | the company's accident insurance percentage | Asetukset, Vakuutukset |
totalAccruedHolidayGroupLifeInsurance | the company's group life percentage | Asetukset, 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
- Create a test employee and employment (Employees and employments) and check that holiday years exist:
GET /v03/api/holidays. - Call the report shape with a date in the current month. Expect
200and the seven fields. - Call the ledger shape with
target=default. Compare the sum of the rows withsummary.holidayCalc. A gap of the accident and group life figures is expected. - 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

