Skip to content

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 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 below.

The default flow ​

Default salary payment flowSix 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.1 · The employer creates the payrollpayroll draft · calculations payrollDraft · no invoices yet2 · The employer commits the paymentpaymentStarted · net unread · tax and union preview3 · The channel reads the net invoicenet invoice read4 · The channel reports the net invoice paidcalculation paymentSucceeded · net invoice paid5 · Tax and union invoices released and paidday-6 monthly run of the next month: unread → paid6 · The payroll closespayroll paymentSucceeded — every calculation succeededCancel before the netinvoice is paidinvoices canceledcalculations payrollDraftpayroll back to draft— edit and submit again
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.

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 ​

StatusWhat it means
draftCreated, not yet submitted for payment. Editable.
waitingPartnerApprovalWaiting for the other party, for example the accounting firm, to process it. Used by the Pro API.
paymentAllowedApproved for payment by the company or the accounting firm. Used by the Pro API.
paymentStartedPayment is in progress; calculations and invoices have been created.
paymentSucceededAll calculations have been paid or otherwise handled. Final — cannot be edited.
paymentCanceledAll calculations have been cancelled or refunded.

Salary calculation ​

StatusWhat it means
draftA standalone calculation, not yet submitted for payment.
payrollDraftA draft that is already part of a payroll.
proDraftA draft made by the accounting firm, hidden from the company until it is released.
waitingApprovalWaiting for approval, and possibly input, from the company.
sharedApprovedA calculation a worker shared with the employer, which the employer has approved.
paymentStartedPayment is in progress.
paymentSucceededThe 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).
paymentCanceledCancelled by Salaxy after the payment started. An employer's cancel before payment returns the calculation to payrollDraft instead (see Cancelling a payment).
paymentRefundedCancelled by Salaxy and refunded to the employer.
paymentErrorThe payment failed and needs manual attention.

A payment can be committed from draft, payrollDraft, proDraft, waitingApproval and sharedApproved; see Set for payment.

Invoice ​

StatusWhat it means
previewA 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.
forecastAn 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.
unreadReleased to the payment channel, not yet picked up.
readThe payment channel has fetched the invoice.
paidThe channel has reported the invoice paid.
canceledThe 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 ​

TypeWhat it is
netThe worker's take-home salary. The trigger of the flow — paying it closes the calculation.
grossOnly on customer funds account channels: the employer's payment of the payroll to Salaxy. On those channels it replaces net as the trigger.
taxThe employer's combined payment to the Tax Administration (see sub-types below).
foreclosureWage garnishment (ulosmittaus) to the enforcement authority.
unionTrade 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.

TypeWhat it is
pensionEarnings-related pension insurance contribution (TyEL, työeläkemaksu). The employer reports and pays it with their pension company.
unemploymentUnemployment 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.

TypeBecomes unreadStatus before that
netImmediately, when the payment is committedDoes not exist yet
foreclosureImmediately, when the payment is committedDoes not exist yet
taxDay 6 of the month after the salary month, in the monthly runpreview from commit until then
unionDay 6 of the month after the salary month, in the same runpreview from commit until then
pensionNeverforecast, permanently
unemploymentNeverforecast, 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:

  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), 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 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).

Next: Salary calculations

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.