# 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](https://code.salaxy.com/integration/accounting-data.md).
Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production.

*Diagram: Holiday 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. (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](https://code.salaxy.com/integration/accounting-data.md).
- **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.

| 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](https://code.salaxy.com/integration/accounting-data.md#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.

| 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

- **`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.

| 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 `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.

| 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

1. Create a test employee and employment ([Employees and employments](https://code.salaxy.com/integration/employments.md)) 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](https://code.salaxy.com/reference/test-endpoints.md).

## 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](https://code.salaxy.com/integration/monthly-cycle.md)
