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

## The endpoint sequence

| # | Method | Endpoint | Does |
|---|---|---|---|
| 1 | `POST` | `/v03/api/payroll` | Creates the payroll |
| 2 | `GET` | `/v03/api/employments?$filter=otherPartyInfo/officialId eq '190372-942M'` | Finds the employment by the worker's identity code |
| 3 | `GET` | `/v03/api/employments/{id}` | Reads the full employment |
| 4 | `POST` | `/v03/api/calculations/update-from-employment?save=false&updateRows=true` | Fills a calculation from the employment — its default salary rows and other employment data — without saving |
| 5 | `POST` | `/v03/api/calculations` | Saves the calculation |
| 6 | `POST` | `/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](https://code.salaxy.com/get-started/rest/set-for-payment.md).

## 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](https://code.salaxy.com/get-started/rest/create-employees.md), 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](https://code.salaxy.com/integration/payroll-lifecycle.md#salary-calculation).

**Save for the next step:**
- `id` — the calculation, to add to the payroll below, and to follow its payment in [6. Track the payment status](https://code.salaxy.com/get-started/rest/track-status.md).

## 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](https://code.salaxy.com/docs/create-payroll). The runnable samples stay there; the steps and endpoints are here.

← [3. Create employees](https://code.salaxy.com/get-started/rest/create-employees.md) · [5. Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md) →
