> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ontime.hosai.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Payroll overview
> The five-stage payroll cycle, what each stage locks, and who is allowed to run it.
Payroll in OnTime is a **cycle**: one run per month, moving through five stages in order. It reads attendance rather than owning it, so most of what determines the numbers has already happened before the cycle starts.
## The five stages
```mermaid theme={null}
stateDiagram-v2
direction LR
[*] --> Started: start a cycle
Started --> Frozen: freeze attendance
Frozen --> InputsDone: mark inputs complete
InputsDone --> Calculated: calculate
Calculated --> Approved: approve
Approved --> Disbursed: disburse
Disbursed --> [*]
Calculated --> Calculated: recalculate
```
Each stage is gated on the one before it. Attempting them out of order is refused — you cannot calculate a cycle whose inputs are not marked complete, and you cannot disburse one that has not been approved.
| Stage | What it does | What it locks |
| ---------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Freeze attendance** | Marks every day record in the month as frozen. | Punches, regularizations, overtime approvals and day overrides for that month are now refused. |
| **Inputs & overrides** | The window for line-level corrections before the maths runs. | Nothing new; ends when you mark it complete. |
| **Calculate** | Runs the engine over every employee: earnings, deductions, overtime, loss of pay, net. | Produces the run lines and the anomaly flags. |
| **Approve** | Sign-off on the calculated numbers. | Approval is tied to the exact calculation it approved — recalculating invalidates it. |
| **Disburse** | Materializes payslips. | The cycle is closed. |
**Disburse is the point of no return.** It creates the `Payslip` rows employees see and marks the cycle disbursed. There is no un-disburse.
## What freezing actually does
Freezing sets a flag on **every day record in the month**, for every employee. From that moment:
* New punches for those dates are refused.
* Approving a regularization that would rewrite one of those days is refused, and the whole approval rolls back.
* Approving overtime on one of those days is likewise refused.
Clear your regularization and overtime queues **before** you freeze. An approver hitting a wall of refusals after the freeze is the most common payroll-week friction.
An administrator can still lift the freeze on an individual day through a day override — but that is a deliberate, audited exception, not the normal path.
## Recalculating
You can calculate more than once. Recalculating rebuilds every run line from current data — and **clears the approval**, because the numbers that were approved no longer exist.
Adding a line-level override does not automatically recalculate. The review screen warns you when overrides exist on an already-calculated cycle; you have to re-run Calculate for them to take effect.
## Who can do what
| Permission | Grants |
| --------------- | --------------------------------------------------------------------- |
| `payroll:read` | View cycles, run review, components, compensation and payslips. |
| `payroll:write` | Start cycles, advance stages, edit components, file salary revisions. |
Both sit with the **HR** and **Admin** presets. Managers and employees have neither — employees see their own payslips through `pay:read`, which is a different key.
Every stage transition is written to the audit log.
## Where to go
The earnings and deductions that make up a payslip.
Per-employee salary structure and revision history.
The month-end runbook, stage by stage.
Correcting a single line before the maths runs.
The admin browser and what employees see.