Appearance
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 or an agent on the MCP server.
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
netinvoice 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
netinvoice is the central event. When the channel reports it paid, the calculation closes. On a customer funds account channel thegrossinvoice takes this role instead: see Customer funds account below.
The default flow
In six lines:
- The employer creates a payroll → payroll
draft, calculationspayrollDraft. - The employer commits the payment → invoices are generated; payroll and calculations become
paymentStarted; thenetinvoice goesunread, thetaxandunioninvoicespreview. - The channel reads the net invoice →
net: read. - The channel pays the net invoice →
net: paid, calculationpaymentSucceeded. - The
taxandunioninvoices are finalised in the monthly run on day 6 of the following month, released asunread, and paid →tax: paid,union: paid. - 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
grossinvoice is added. It is the employer's payment of the whole payroll to Salaxy, created at commit in addition to the other invoices. - The
grossinvoice drives the calculation. When it is paid, the calculations becomepaymentSucceeded. Apaidreport on thenetinvoice does not change the calculation on these channels. paymentSucceededhere 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.
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.
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. |
paymentAllowed | Approved for payment by the company or the accounting firm. Used by the Pro API. |
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). |
paymentCanceled | Cancelled by Salaxy after the payment started. An employer's cancel before payment returns the calculation to payrollDraft instead (see 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.
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.
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:
- 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 nounioninvoice. - Zero total, already settled. A zero-total invoice may be set straight to
paidwithout being released. Whether this happens depends on the payment channel. - Retroactive salary. When a calculation carries
workflow.salaryDateKind: inPast(retroactive salary), the worker was already paid outside Salaxy, so no money moves. On many channels thenetandforeclosureinvoices are created aspaidand 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
taxandunioninvoices 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
netinvoice is paid, the whole payroll reverts. While the payroll ispaymentStartedand no invoice ispaid, the employer can cancel: each invoice is cancelled through its channel, every calculation returns topayrollDraft, and the payroll returns todraftwith its pay date cleared. It can then be edited and submitted again. - Cancelling after payment. On most payment channels, reporting a paid
netinvoicecanceledmoves its calculation topaymentCanceled, and the earnings payment report is withdrawn. On customer funds account channels only Salaxy can cancel a paidgrossinvoice. Refunds (paymentRefunded) are handled by Salaxy.
In the agentic path
The same lifecycle holds for an agent. The payroll-process skill 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. Committing a payment always needs a person's approval (Permissions and human approval).
Related
- Core concepts — account, worker, employment, calculation, payroll
- Monthly cycle · Invoices and payments · Set for payment · Track the payment status
Next: Salary calculations

