# 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](https://code.salaxy.com/get-started/environments.md) for demo and production.

*Diagram: You 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. (Grey: what you send. Purple: what Salaxy does and returns.)*

The calculation is the unit of payment. Creating a [payroll](https://code.salaxy.com/get-started/rest/create-payroll.md) groups calculations under one pay date; the [statuses](https://code.salaxy.com/integration/payroll-lifecycle.md#salary-calculation) and the payment flow are in [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md). 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](https://code.salaxy.com/integration/employments.md); `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)](https://code.salaxy.com/reference/wage-types.md).
- **`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](https://code.salaxy.com/reference/yearly-numbers.md).

## Two ways to build rows

### From the employment

For monthly paid employees, the standard rows (monthly salary, recurring benefits) are saved on the [employment](https://code.salaxy.com/integration/employments.md). 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](https://code.salaxy.com/get-started/rest/create-payroll.md).

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

## 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](https://code.salaxy.com/reference/queries.md) |
| `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](#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.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](https://code.salaxy.com/integration/tax-cards.md).

The invoices Salaxy creates from the result are in [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md).

## 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](https://code.salaxy.com/get-started/rest/set-for-payment.md).
- **`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](https://code.salaxy.com/reference/errors.md).

## 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

1. Get a test account and token: [Get a test account](https://code.salaxy.com/get-started/test-account.md).
2. Take an employment from [Create employees](https://code.salaxy.com/get-started/rest/create-employees.md). Test data is in [Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md).
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](https://code.salaxy.com/reference/wage-types.md); 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](https://code.salaxy.com/integration/invoices-and-payments.md)
