# Payroll lifecycle and statuses

How a payroll, the salary calculations inside it and the invoices they produce move through their statuses, from creation to payment to closure. The same lifecycle applies whether your integration uses the [REST API](https://code.salaxy.com/get-started/rest/index.md) or an agent on the [MCP server](https://code.salaxy.com/get-started/agentic/index.md).

## The three entities

- **Payroll** (*palkkalista*) — a pay event that groups one or more salary calculations under one pay date.
- **Salary calculation** (*palkkalaskelma*) — the calculation for one worker: gross salary, deductions, taxes, net salary.
- **Invoice** (*lasku*) — a **payment instruction** sent to a payment channel: a bank, an accounting system or a partner integration. A calculation produces a `net` invoice for the worker's salary, plus invoices for the authorities.

## How they relate

- A salary calculation can exist on its own (a single payment) or belong to a payroll.
- **The payroll's status is derived from its calculations.** The payroll succeeds only when *every* calculation succeeds, and reverts only when *every* calculation reverts; partial states leave it unchanged.
- **Invoices are generated automatically** when the payment is committed — you never create them.
- **The `net` invoice is the central event.** When the channel reports it paid, the calculation closes. On a customer funds account channel the `gross` invoice takes this role instead: see [Customer funds account](#customer-funds-account-channels) below.

## The default flow

*Diagram: Six steps: the employer creates the payroll, commits the payment, the channel reads and then pays the net invoice, tax and union invoices are released in the day-6 monthly run and paid, and the payroll closes. Before the net invoice is paid, the payment can be cancelled and the payroll returns to draft. (Green: paid and closed. Orange, dashed: cancelling before the net invoice is paid.)*

In six lines:

1. The employer creates a payroll → payroll `draft`, calculations `payrollDraft`.
2. The employer commits the payment → invoices are generated; payroll and calculations become `paymentStarted`; the `net` invoice goes `unread`, the `tax` and `union` invoices `preview`.
3. The channel reads the net invoice → `net: read`.
4. The channel pays the net invoice → `net: paid`, calculation `paymentSucceeded`.
5. The `tax` and `union` invoices are finalised in the monthly run on day 6 of the following month, released as `unread`, and paid → `tax: paid`, `union: paid`.
6. Once every calculation has succeeded → payroll `paymentSucceeded`.

The invoice statuses you actually handle are `unread`, `read`, `paid` and `canceled` — plus `preview` for the periodic `tax` and `union` invoices until the monthly run finalises them.

### Customer funds account channels

When Salaxy pays from a customer funds account, the employer pays Salaxy first:

- **A `gross` invoice is added.** It is the employer's payment of the whole payroll to Salaxy, created at commit in addition to the other invoices.
- **The `gross` invoice drives the calculation.** When it is paid, the calculations become `paymentSucceeded`. A `paid` report on the `net` invoice does not change the calculation on these channels.
- **`paymentSucceeded` here means Salaxy has received the employer's funds**, not that the worker is paid. Salaxy pays the worker, the tax and the other recipients after that. See [Payment channels](https://code.salaxy.com/integration/payment-channels.md#salaxy-pays-from-a-customer-funds-account).

## Statuses

These tables list the **main** statuses an integration meets. Values are shown as the API serialises them, in lowerCamelCase. Match them exactly when filtering, querying or comparing. The full enums are the `PayrollStatus`, `CalculationStatus` and `InvoiceStatus` schemas in the [REST API reference](https://code.salaxy.com/reference/rest-api.md).

### Payroll

| Status | What it means |
|---|---|
| `draft` | Created, not yet submitted for payment. Editable. |
| `waitingPartnerApproval` | Waiting for the other party, for example the accounting firm, to process it. Used by the [Pro API](https://code.salaxy.com/integration/pro-api.md). |
| `paymentAllowed` | Approved for payment by the company or the accounting firm. Used by the [Pro API](https://code.salaxy.com/integration/pro-api.md). |
| `paymentStarted` | Payment is in progress; calculations and invoices have been created. |
| `paymentSucceeded` | All calculations have been paid or otherwise handled. **Final** — cannot be edited. |
| `paymentCanceled` | All calculations have been cancelled or refunded. |

### Salary calculation

| Status | What it means |
|---|---|
| `draft` | A standalone calculation, not yet submitted for payment. |
| `payrollDraft` | A draft that is already part of a payroll. |
| `proDraft` | A draft made by the accounting firm, hidden from the company until it is released. |
| `waitingApproval` | Waiting for approval, and possibly input, from the company. |
| `sharedApproved` | A calculation a worker shared with the employer, which the employer has approved. |
| `paymentStarted` | Payment is in progress. |
| `paymentSucceeded` | The channel has confirmed the payment. The normal end state. On a customer funds account channel it means Salaxy has received the employer's funds (see [above](#customer-funds-account-channels)). |
| `paymentCanceled` | Cancelled by Salaxy after the payment started. An employer's cancel before payment returns the calculation to `payrollDraft` instead (see [Cancelling a payment](#cancelling-a-payment)). |
| `paymentRefunded` | Cancelled by Salaxy and refunded to the employer. |
| `paymentError` | The payment failed and needs manual attention. |

A payment can be committed from `draft`, `payrollDraft`, `proDraft`, `waitingApproval` and `sharedApproved`; see [Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md).

### Invoice

| Status | What it means |
|---|---|
| `preview` | A real but not yet final invoice. The periodic `tax` and `union` invoices stay here until the day-6 monthly run finalises them and releases them as `unread`. A `preview` invoice may still be regenerated — **do not pay against it**. |
| `forecast` | An informational estimate, **never released to a payment channel**. Used by the forecast-only types `pension` and `unemployment`; the amount is reported and paid outside Salaxy. |
| `unread` | Released to the payment channel, not yet picked up. |
| `read` | The payment channel has fetched the invoice. |
| `paid` | The channel has reported the invoice paid. |
| `canceled` | The invoice was cancelled. |

## Invoice types

A calculation produces two groups of invoices: **payable** invoices, which move through a payment channel and drive the flow above, and **forecast-only** invoices, which Salaxy never sends to a channel.

### Payable

| Type | What it is |
|---|---|
| `net` | The worker's take-home salary. The trigger of the flow — paying it closes the calculation. |
| `gross` | Only on customer funds account channels: the employer's payment of the payroll to Salaxy. On those channels it replaces `net` as the trigger. |
| `tax` | The employer's combined payment to the Tax Administration (see sub-types below). |
| `foreclosure` | Wage garnishment (*ulosmittaus*) to the enforcement authority. |
| `union` | Trade union membership fee (*AY-jäsenmaksu*). Periodic like `tax`: created as `preview`, released in the day-6 monthly run. Not the Employment Fund contribution — that is `unemployment` below. |

**Tax sub-types are rows inside the `tax` invoice, not separate invoices:** `taxWithholding` (*ennakonpidätys*), `taxSocialSecurity` (employer's health insurance contribution, *sava-maksu*) and `taxAtSource` (*lähdevero*).

### Forecast-only

Always `forecast`: informational estimates, never released to a channel. The responsible party reports and pays the amount directly.

| Type | What it is |
|---|---|
| `pension` | Earnings-related pension insurance contribution (TyEL, *työeläkemaksu*). The employer reports and pays it with their pension company. |
| `unemployment` | Unemployment insurance contribution to the Employment Fund (*Työllisyysrahasto*). The Fund bills the employer separately. |

**There is no insurance invoice.** The two mandatory insurance contributions Salaxy calculates are the forecast-only types above. Accident insurance (*tapaturmavakuutus*) and group life insurance produce no invoice at all: Salaxy stores the contract, but the insurance company bills the employer directly.

## When an invoice becomes `unread`

`unread` means *released to the payment channel and waiting to be picked up* — the status your integration polls for. Invoices do not all reach it at the same time, and some never do.

| Type | Becomes `unread` | Status before that |
|---|---|---|
| `net` | Immediately, when the payment is committed | Does not exist yet |
| `foreclosure` | Immediately, when the payment is committed | Does not exist yet |
| `tax` | Day 6 of the month *after* the salary month, in the monthly run | `preview` from commit until then |
| `union` | Day 6 of the month after the salary month, in the same run | `preview` from commit until then |
| `pension` | Never | `forecast`, permanently |
| `unemployment` | Never | `forecast`, permanently |

This is the timing on most payment channels. A few channels release the `tax` and `union` invoices as soon as all their salaries are paid, and customer funds account channels work differently: see [Monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md#what-the-invoices-do).

So one commit gives you the `net` invoice at once, and the `tax` and `union` invoices up to five weeks later. **Pay the `net` invoice as soon as it appears** — do not wait for a complete set.

## Three reasons an expected invoice never appears

A calculation does *not* produce one invoice of every type. None of these is an error:

1. **Nothing to pay.** When a type's amount is zero, or the type does not apply, the invoice is created as `canceled`. A worker with no union deduction produces no `union` invoice.
2. **Zero total, already settled.** A zero-total invoice may be set straight to `paid` without being released. Whether this happens depends on the payment channel.
3. **Retroactive salary.** When a calculation carries `workflow.salaryDateKind: inPast` ([retroactive salary](https://code.salaxy.com/integration/calculations.md#salary-date-and-retroactive-salary)), the worker was already paid outside Salaxy, so no money moves. On many channels the `net` and `foreclosure` invoices are created as `paid` and never released — also channel-specific.

Cases 2 and 3 are **fixed for a given payment channel**, not decided per invoice. Confirm with Salaxy which applies to yours; building for both is safe.

## What this means for polling

- **Poll for `unread`, then act on what is there.** Do not compute an expected invoice set and treat a shortfall as a failure.
- **Never assume a fixed number of invoices per calculation.** It varies by employer, period and channel.
- **Keep polling after the salary month closes.** The `tax` and `union` invoices for a January salary appear on 6 February.
- **A quiet invoice is not a stuck invoice.** Salaxy never times an invoice out.

## Cancelling a payment

- **Before the `net` invoice is paid, the whole payroll reverts.** While the payroll is `paymentStarted` and no invoice is `paid`, the employer can cancel: each invoice is cancelled through its channel, every calculation returns to `payrollDraft`, and the payroll returns to `draft` with its pay date cleared. It can then be edited and submitted again.
- **Cancelling after payment.** On most payment channels, reporting a paid `net` invoice `canceled` moves its calculation to `paymentCanceled`, and the earnings payment report is withdrawn. On customer funds account channels only Salaxy can cancel a paid `gross` invoice. Refunds (`paymentRefunded`) are handled by Salaxy.

## In the agentic path

The same lifecycle holds for an agent. The [`payroll-process` skill](https://code.salaxy.com/reference/skills.md#payroll-process) explains it to the agent — what a status means and what happens next — and the tools for payrolls and invoices are listed with their status in [Availability](https://code.salaxy.com/about/availability.md#by-skill-area). Committing a payment always needs a person's approval ([Permissions and human approval](https://code.salaxy.com/security/permissions.md)).

## Related

- [Core concepts](https://code.salaxy.com/about/concepts.md) — account, worker, employment, calculation, payroll
- [Monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md) · [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md) · [Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md) · [Track the payment status](https://code.salaxy.com/get-started/rest/track-status.md)

**Next:** [Salary calculations](https://code.salaxy.com/integration/calculations.md)
