Appearance
Salary calculations
A salary calculation (palkkalaskelma) is the payslip as a data object: you send rows (hours, amounts, expenses), Salaxy applies the Finnish pay rules and returns the result — gross, taxes, net pay and the employer's cost. You never calculate tax or side costs yourself.
Examples use the test environment (test-secure.salaxy.com); see Environments for demo and production.
The calculation is the unit of payment. Creating a payroll groups calculations under one pay date; the statuses and the payment flow are in Payroll lifecycle and statuses. This page covers the calculation itself.
How a calculation looks
| Part | What it holds |
|---|---|
workflow | status, and the salary dates: salaryDate, requestedSalaryDate, salaryDateKind |
employer | The paying company. isSelf: true means the account you act as |
worker | The employee. employmentId links the employment; accountId is the worker's account |
info | Work period (workStartDate, workEndDate), paymentChannel, payrollId, workerSourceId and sourceId for your own ids |
rows | The input: one row per pay item |
result | The output: totals, workerCalc, employerCalc, validation, and the Incomes Register rows. Read-only |
You write rows (and the parts above them); Salaxy fills result every time the calculation is saved or recalculated.
Rows
A row says what is paid (rowType), how much (count × price) and, optionally, a message for the payslip. rowType is a camelCase string on the wire, never a number.
json
{
"workflow": { "status": "payrollDraft" },
"employer": { "isSelf": true },
"worker": { "employmentId": "<employment id>", "accountId": "<worker account id>" },
"info": { "workStartDate": "2026-08-01", "workEndDate": "2026-08-31" },
"rows": [
{ "rowType": "hourlySalary", "count": 35, "price": 65 },
{ "rowType": "remuneration", "count": 1, "price": 2500, "message": "Bonus 2026", "data": { "kind": "bonusPay" } }
]
}- Every wage type is a
rowType: salary, bonus, overtime, benefits, holiday pay, expense compensations, deductions. Each has a default unit, a default price and the Incomes Register income types it is reported as. The full list is in Wage types (row types). data.kindpicks a variant of a row type, for examplebonusPayonremuneration. Rows with extra detail carry it indata: an overtime row,hourlySalaryWithWorkingTimeCompensationwithdata.kindovertimeCompensation, lists its extra pay indata.compensationRows(unit,count,price).- Units are
count,percent,days,kilometers,hours,weeksormonths. A row type has a default; setunitonly to override it. - Negative prices are accepted only on
monthlySalary,hourlySalary,salary,timeRatePay,compensation,expensesandirIncomeType. On other row types a negative price is a validation error. - Yearly numbers. Some default prices change every year: daily allowance, partial daily allowance, meal compensation and mileage with the worker's own car. See Yearly numbers.
Two ways to build rows
From the employment
For monthly paid employees, the standard rows (monthly salary, recurring benefits) are saved on the employment. Salaxy copies them into the calculation; you add only what changes this month.
| Method | Path | Purpose |
|---|---|---|
POST | /v03/api/calculations/update-from-employment?save=false&updateRows=true | Replaces the calculation's rows with the employment's rows, and sets the tax card and pension. With save=false nothing is stored |
Then push the month's rows (overtime, bonus, expenses) into rows and save. The same call is used in Create a payroll.
Your own rows
For hourly pay, worktime from your own system or one-off payments, build rows yourself from your data. Importing worktime in bulk is in Worktime import.
Endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /v03/api/calculations/new | A blank calculation object to fill in |
POST | /v03/api/calculator/recalculate | Calculates the calculation you post and stores nothing. The safe way to try rows |
POST | /v03/api/calculations | Saves the calculation (create or update) and returns it with id and result |
GET | /v03/api/calculations/{id} | Reads one calculation |
GET | /v03/api/calculations?$filter=status eq 'draft' | Lists calculations; query syntax in Queries |
DELETE | /v03/api/calculations/{id} | Deletes a calculation |
POST | /v03/api/payroll/validate | Validates a payroll before it is committed |
Saving does not require a valid calculation. See Validation below.
Reading the result
After a save or a recalculation, result holds everything the payslip shows. The main parts:
| Part | Fields to read | Meaning |
|---|---|---|
result.totals | totalGrossSalary, totalBaseSalary, totalExpenses, totalPayable, totalTaxable | The sums of the rows, common to worker and employer |
result.workerCalc | salaryPayment, tax, pension, unemploymentInsurance, socialSecurity, unionPayment, foreclosure, totalWorkerPayment | The worker's side: deductions and what the worker receives |
result.employerCalc | totalSalaryCost, mandatorySideCosts, pension, unemployment, socialSecurity, palkkaus, service, finalCost | The employer's side: side costs and the total cost |
workerCalc.salaryPaymentis the net pay. It is gross minus the worker's deductions.employerCalc.totalSalaryCostincludes the Salaxy fee, as doestotalPayment. The cost without the fee ismandatorySideCosts, ortotalSalaryCostminuspalkkausandservice. Compare costs on the same basis, or you will see a difference that is only the fee.- Deductions come off in a fixed order, each from what is left: withholding tax, tax at source, foreclosure, salary advance, the worker's pension, unemployment insurance and health insurance contributions, then the union fee, then other deductions. The advance and the three contributions are capped at what is left. The union fee and other deductions are all or nothing: they are dropped entirely when the full amount does not fit. Do not recompute this in your own code; read
result. - A tax card with an income limit switches to its additional percentage when the year's earlier income passes the limit. The income log is on the tax card, not in the calculation; see Tax cards.
The invoices Salaxy creates from the result are in Invoices and payments.
Validation
Validation is server-side, and the API returns HTTP 200. A calculation that fails validation is still saved and returned. The failures are in result.validation:
json
{
"result": {
"validation": {
"isValid": false,
"hasAllRequiredFields": true,
"errors": [
{
"key": "result.rows[0]",
"type": "invalid",
"msg": "Auton päästöarvon tulee olla 0 vuodesta 2026 eteenpäin",
"code": "Calc.InvalidCarBenefitEmissionValues"
}
]
}
}
}typeisgeneral,required,invalidorwarning.msgis currently in Finnish.- Payment is the gate. Committing a calculation for payment fails when it has any error that is not a
warning. The failure message is generic ("the calculation is not valid") and does not name the field, so readresult.validation.errorsyourself. - Check before you commit. Read
result.validation.isValidafter every save, and callPOST /v03/api/payroll/validatebefore setting a payroll for payment. codeis for your own mapping. Show your users your own text for the codes you meet;msgandkeyare not stable identifiers. HTTP-level failures follow Errors.
Salary date and retroactive salary
workflow.salaryDate is the day the net salary reaches the worker. You can ask for a date with requestedSalaryDate; the server sets the real salaryDate from it by the banking-day rules. A date in the past is not accepted as a normal salary: both recalculate and a save reset it to today.
Retroactive salary (takautuva palkka) is for a salary that was already paid outside Salaxy and only needs to be registered, so it is reported to the Incomes Register on the past pay date. Set workflow.salaryDateKind to inPast (on a payroll, input.salaryDateKind; it is copied to every calculation in it).
json
{
"workflow": { "status": "payrollDraft", "salaryDateKind": "inPast", "requestedSalaryDate": "2026-05-29" }
}What inPast changes:
| Area | Behaviour |
|---|---|
| Salary date | Frozen to the date you give. It is not moved by the banking-day rules |
net invoice | Marked paymentType: "salaryInPast". On many payment channels it is created already paid, because no money moves. On channels with their own payment workflow it is released as unread as usual. This is fixed per channel; confirm yours with Salaxy |
| Tax and union invoices | Still generated, unless the salary month is already closed: then they are created as canceled |
| Pension invoice | Not generated; the pension company bills the employer from the Incomes Register report |
| Incomes Register | Reporting still starts when the net invoice is paid, on your past date. Late filing can bring penalties from the authorities |
| Statuses | The calculation still goes payrollDraft → paymentStarted → paymentSucceeded |
Check the value after saving. inPast is honoured only on payment channels that allow retroactive salary. On any other channel it is silently reset to default on save, with no error, and the calculation is paid as a normal salary. Always read workflow.salaryDateKind back from the saved calculation.
Test it
- Get a test account and token: Get a test account.
- Take an employment from Create employees. Test data is in Test endpoints and test data.
GET /v03/api/calculations/new, fillworker.employmentIdand onehourlySalaryrow (count35,price65), thenPOSTit to/v03/api/calculator/recalculate. Expectresult.totals,result.workerCalcandresult.employerCalcfilled in.- Add a row with a negative
priceon a type that does not allow it, and expect an error inresult.validation, not an HTTP error. - Save with
POST /v03/api/calculationsand read the calculation back withGET /v03/api/calculations/{id}.
Checklist
- Rows are built with
rowTypestrings from the wage types list; you do not calculate tax, pension or side costs yourself. - You read net pay from
workerCalc.salaryPaymentand employer cost fromemployerCalc, and know thattotalSalaryCostincludes the Salaxy fee. - You check
result.validationafter every save, and callpayroll/validatebefore committing. - Retroactive salary is checked after saving:
workflow.salaryDateKindis stillinPast. - You use
POST /v03/api/calculator/recalculatefor previews and tests, so nothing is stored.
Next: Invoices and payments

