Skip to content

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.

From rows to a calculated payslipYou send a salary calculation with rows such as hours and amounts. The Salaxy engine applies the pay rules, tax and side costs. You read back the result: the worker's net pay, the employer's total cost, and the validation outcome.YOU SENDSALAXY CALCULATESYOU READRowshours, amounts, expensesSalaxy enginepay rules, tax, side costsWorker: net payEmployer: total costValidation
Grey: what you send. Purple: what Salaxy does and returns.

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 ​

PartWhat it holds
workflowstatus, and the salary dates: salaryDate, requestedSalaryDate, salaryDateKind
employerThe paying company. isSelf: true means the account you act as
workerThe employee. employmentId links the employment; accountId is the worker's account
infoWork period (workStartDate, workEndDate), paymentChannel, payrollId, workerSourceId and sourceId for your own ids
rowsThe input: one row per pay item
resultThe 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.kind picks a variant of a row type, for example bonusPay on remuneration. Rows with extra detail carry it in data: an overtime row, hourlySalaryWithWorkingTimeCompensation with data.kind overtimeCompensation, lists its extra pay in data.compensationRows (unit, count, price).
  • Units are count, percent, days, kilometers, hours, weeks or months. A row type has a default; set unit only to override it.
  • Negative prices are accepted only on monthlySalary, hourlySalary, salary, timeRatePay, compensation, expenses and irIncomeType. 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.

MethodPathPurpose
POST/v03/api/calculations/update-from-employment?save=false&updateRows=trueReplaces 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 ​

MethodPathPurpose
GET/v03/api/calculations/newA blank calculation object to fill in
POST/v03/api/calculator/recalculateCalculates the calculation you post and stores nothing. The safe way to try rows
POST/v03/api/calculationsSaves 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/validateValidates 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:

PartFields to readMeaning
result.totalstotalGrossSalary, totalBaseSalary, totalExpenses, totalPayable, totalTaxableThe sums of the rows, common to worker and employer
result.workerCalcsalaryPayment, tax, pension, unemploymentInsurance, socialSecurity, unionPayment, foreclosure, totalWorkerPaymentThe worker's side: deductions and what the worker receives
result.employerCalctotalSalaryCost, mandatorySideCosts, pension, unemployment, socialSecurity, palkkaus, service, finalCostThe employer's side: side costs and the total cost
  • workerCalc.salaryPayment is the net pay. It is gross minus the worker's deductions.
  • employerCalc.totalSalaryCost includes the Salaxy fee, as does totalPayment. The cost without the fee is mandatorySideCosts, or totalSalaryCost minus palkkaus and service. 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"
        }
      ]
    }
  }
}
  • type is general, required, invalid or warning. msg is 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 read result.validation.errors yourself.
  • Check before you commit. Read result.validation.isValid after every save, and call POST /v03/api/payroll/validate before setting a payroll for payment.
  • code is for your own mapping. Show your users your own text for the codes you meet; msg and key are 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:

AreaBehaviour
Salary dateFrozen to the date you give. It is not moved by the banking-day rules
net invoiceMarked 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 invoicesStill generated, unless the salary month is already closed: then they are created as canceled
Pension invoiceNot generated; the pension company bills the employer from the Incomes Register report
Incomes RegisterReporting still starts when the net invoice is paid, on your past date. Late filing can bring penalties from the authorities
StatusesThe 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 ​

  1. Get a test account and token: Get a test account.
  2. Take an employment from Create employees. Test data is in Test endpoints and test data.
  3. GET /v03/api/calculations/new, fill worker.employmentId and one hourlySalary row (count 35, price 65), then POST it to /v03/api/calculator/recalculate. Expect result.totals, result.workerCalc and result.employerCalc filled in.
  4. Add a row with a negative price on a type that does not allow it, and expect an error in result.validation, not an HTTP error.
  5. Save with POST /v03/api/calculations and read the calculation back with GET /v03/api/calculations/{id}.

Checklist ​

  • Rows are built with rowType strings from the wage types list; you do not calculate tax, pension or side costs yourself.
  • You read net pay from workerCalc.salaryPayment and employer cost from employerCalc, and know that totalSalaryCost includes the Salaxy fee.
  • You check result.validation after every save, and call payroll/validate before committing.
  • Retroactive salary is checked after saving: workflow.salaryDateKind is still inPast.
  • You use POST /v03/api/calculator/recalculate for previews and tests, so nothing is stored.

Next: Invoices and payments

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.