Skip to content

4. Create a payroll ​

A payroll groups the salary calculations paid on one date. In this step you create a payroll, build a calculation for the employee from their employment, and add it to the payroll.

Examples use the test environment (test-secure.salaxy.com); see Environments for demo and production.

The endpoint sequence ​

#MethodEndpointDoes
1POST/v03/api/payrollCreates the payroll
2GET/v03/api/employments?$filter=otherPartyInfo/officialId eq '190372-942M'Finds the employment by the worker's identity code
3GET/v03/api/employments/{id}Reads the full employment
4POST/v03/api/calculations/update-from-employment?save=false&updateRows=trueFills a calculation from the employment — its default salary rows and other employment data — without saving
5POST/v03/api/calculationsSaves the calculation
6POST/v03/api/payroll/add-calc?ids={calculation ids}Adds the calculations to the payroll

1. The payroll ​

json
{
  "input": {
    "title": "Payroll August 2025",
    "period": { "start": "2025-08-01", "end": "2025-08-31", "daysCount": 21 },
    "salaryDate": "2025-08-31",
    "wageBasis": "monthly",
    "paymentChannel": "palkkausManual",
    "calculations": []
  },
  "info": {},
  "calcs": [],
  "validations": [],
  "workflowData": {}
}

paymentChannel decides how the money moves; palkkausManual is for trying things out, and a real integration uses the channel set up for it.

The response is the new payroll:

json
{
  "id": "<payroll id>",
  "info": { "status": "draft", "isReadyForPayment": false },
  "input": { "title": "Payroll August 2025", "calculations": [] }
}

Save for the next step

  • id — the payroll, for adding calculations below and for committing it in step 5.

2–3. Find the employment ​

The list query returns a page of rows (items); take the first row's id and read the full employment with GET /v03/api/employments/{id}. You need its id and info.workerAccountId. If you stored both in step 3, skip this.

4–5. The calculation, filled from the employment ​

Post this to update-from-employment:

json
{
  "workflow": { "status": "payrollDraft" },
  "employer": { "isSelf": true },
  "worker": {
    "employmentId": "<employment id>",
    "accountId": "<employment.info.workerAccountId>"
  }
}

update-from-employment returns the calculation with the employment's default salary rows and settings. Post that result, unchanged, to POST /v03/api/calculations to save it. The saved calculation comes back with its id, its status and the calculated totals:

json
{
  "id": "<calculation id>",
  "workflow": { "status": "payrollDraft" },
  "result": { "totals": { "totalGrossSalary": 3000 } }
}

Its status payrollDraft means a draft that belongs to a payroll — see Payroll lifecycle and statuses.

Save for the next step

6. Add it to the payroll ​

Post the payroll (the response from section 1) to add-calc, with the calculation ids comma-separated in ids. Salaxy adds them to input.calculations and saves the payroll. The payroll stays draft, now with its calculations — ready to be sent for payment. The response is the updated payroll:

json
{
  "id": "<payroll id>",
  "info": { "status": "draft", "isReadyForPayment": true },
  "input": { "calculations": ["<calculation id>"] }
}

info.isReadyForPayment: true means every calculation validates. If it is false, read the payroll's validations before going on.

Check ​

  • The payroll's input.calculations contains your calculation's id.
  • The calculation's status is payrollDraft.
  • POST /v03/api/payroll/validate returns no errors — or only ones you understand and can fix.

Runnable sample

The interactive version of this step — sign in and run it against your test account — is on the current developer site: create payroll. The runnable samples stay there; the steps and endpoints are here.

← 3. Create employees · 5. Set for payment →

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.