Run payroll
A pay run goes from draft to approved to lodged with the ATO, with payslips and a bank payment file along the way. The run-payroll component does all of it; the payrun-history component shows the past. This guide is the sequence underneath, with the concurrency and confirmation rules that make it safe.
Session: an employer session with payruns:read, payruns:write and, for lodgement and the payment file, payruns:lodge and documents:read; components run-payroll and payrun-history.
States
draft → approved → (published) → lodging → accepted or rejected. published is a run whose payslips exist but which has not been lodged; lodged is a run the business lodged from Payroo's own app. The lodgement object on the pay run adds state (none, lodged, accepted, rejected, needs_attention), the channel reference and, on rejection, the ATO's error rows in Payroo's customer wording.
ETags: every write needs If-Match
GET /payruns/{id} returns an ETag like W/"rev-3.v7". Every mutation requires it as If-Match: 428 precondition_required without it, 409 revision_conflict when someone else changed the run first. On conflict, read again and show the user what changed. The runtime does this for you.
1. Create
POST /payruns
Idempotency-Key: <uuid>
{ "period": { "start": "2026-11-02", "end": "2026-11-15" }, "payDate": "2026-11-17" }
The component computes the next period from the pay settings and the latest run; the server takes explicit dates only. 201 with the draft and every eligible employee as a line, ETag: W/"rev-0.v0". Refusals: 422 validation_failed (dates do not fit the frequency, payDate before the period end, or no Idempotency-Key), 409 payrun_period_overlap, 409 precondition_required with error.blockers (no_payable_employee: no active employee with tax details; subscription_inactive).
2. Edit lines
PATCH /payruns/{id}/lines/{employeeId} with If-Match changes one employee's hours or the engine's adjustment items; the engine recomputes the line and the totals and the ETag moves. adjustments replaces the line's list: each line of the pay run carries its current adjustments, so add one by sending the list with it and remove one by sending the list without it. deductions works the same way for fixed-amount deductions (fees, workplace_giving, salary_sacrifice): it replaces the deductions set through this route, marked editable on the line, and leaves the ones set in Payroo's app. Salary sacrifice is taken before tax, the others after; deductions above the net pay are refused. Child support is entered in Payroo's app. allowances takes a fixed amount under one of the ATO's allowance categories; you state taxable and superApplies on each, and neither has a default. DELETE /payruns/{id}/lines/{employeeId} with If-Match removes an employee from the draft; the last employee cannot be removed (409 payrun_not_editable with blocker last_employee). POST /payruns/{id}/lines with { employeeId } and If-Match adds an employee: Payroo builds the line from their pay rate, leave and recurring pay items and recomputes the totals. GET /payruns/{id}/addable-employees lists who can be added: active employees with tax details who started before the period ends and are not on the run. An employee who is added in Payroo's app instead (terminated, a working holiday maker, percentage or protected-earnings recurring items, an employer using awards) is refused with 409 payrun_not_editable and blocker employee_not_addable, whose message gives the reason. 409 payrun_not_editable once the run is approved (reopen first), or when the line carries items the embedded path cannot recompute (termination, lump sums, unused leave, working holiday makers): then error.blockers names the item and the run is edited in Payroo's app.
3. Check readiness
GET /payruns/{id}/readiness projects the engine's own preconditions for publishing and for the payment file, so the user can fix them before approving:
| Blocker | Meaning | Fix |
|---|---|---|
older_draft_exists |
an earlier pay run is still a draft | approve or delete it first |
employee_tax_details_missing |
an employee on the run has no tax details | complete the employee |
employee_details_incomplete |
no date of birth or no postal address with a four-digit postcode | complete the employee |
payer_apca_id_missing |
the employer bank account has no APCA user id or no institution code | Company setup, bank account |
payer_bank_details_invalid |
the employer account cannot be written to a payment file | fix the account |
subscription_inactive |
the company's Payroo subscription is not active | the business renews in Payroo |
4. Approve
Approval freezes the figures and needs two things a page cannot forge:
- An approval intent:
POST /payruns/{id}/approval-intentswithIf-Matchbinds the intent to this revision, these totals and the user.201with the authoritative preview, which the Payroo-origin confirmation frame renders so the user confirms exactly what will be paid. - A step-up: the user confirms in the Payroo dialog (
approve).
Then POST /payruns/{id}/approve with If-Match, X-Approval-Intent and X-Step-Up-Intent. 200 with the approved run. A bare session answers 403 approval_intent_required; an intent minted before a line edit answers 403 approval_intent_mismatch; one older than its lifetime answers 410 approval_intent_expired. Start again from the intent in each case. The RunPayroll component drives this sequence and raises onApproved.
POST /payruns/{id}/reopen with If-Match takes an approved run back to draft, no confirmation needed; 409 payrun_not_editable for any other state.
5. Lodge
POST /payruns/{id}/lodge
If-Match: W/"rev-3.v9"
Idempotency-Key: <uuid>
X-Step-Up-Intent: <from the lodge confirmation>
{ "declaration": true, "lodgerName": "Ada Owner" }
Order of checks: scope, If-Match, Idempotency-Key, body (declaration must be true, lodgerName given), state approved (409 payrun_not_approved otherwise, a second lodge included), step-up lodge (403 step_up_required, nothing written), readiness blockers (409 precondition_required). Then 202 with an operation of kind lodgement whose two steps are the engine's publish (payslips generated) and file (the STP report handed to the ATO channel).
The outcome is asynchronous. The pay run reads lodging until the channel answers, then accepted or rejected; the component polls and raises onOutcome. payrun.lodging, then payrun.accepted or payrun.rejected fire once each on the page bus and as webhooks. A run still lodging after 45 minutes shows lodgement.state: needs_attention: nobody resubmits; Payroo support resolves it, and your user sees that wording. If the operation failed at a step, POST /operations/{id}/resume runs the remaining step; the same Idempotency-Key on lodge replays the same operation.
6. Payment file
POST /payruns/{id}/payment-file/link (scope documents:read) mints a link to the bank file, valid about five minutes, returned once with Cache-Control: no-store. 409 payrun_not_approved on a draft; 409 precondition_required with payer_apca_id_missing or payer_bank_details_invalid. Payrun.paymentFileAvailable tells you in advance whether the call would succeed, so the button can be disabled instead of failing.
History
GET /payruns?financialYear=2027&state=accepted&cursor= lists runs newest pay date first, with totals in cents. The PayrunHistory component renders it with inline detail, payslips and document links (see Payslips and documents).
What you should see
Create answers 201 and payrun.created; after approve, state: approved and payrun.approved; after lodge, 202, then within minutes on sandbox state: accepted with a lodgement.channelReference and payrun.accepted. GET /payruns/{id}/payslips lists one payslip per employee with documentAvailable: true.
Errors you may see
| Status and code | Meaning | Next action |
|---|---|---|
428 precondition_required |
If-Match missing |
send the ETag you read |
409 revision_conflict |
stale ETag | reload and retry |
409 payrun_not_editable |
wrong state for the edit, or an item the embedded path cannot recompute | reopen, or edit in Payroo's app |
409 payrun_not_approved |
lodge or payment file on a run that is not approved | approve first |
409 precondition_required with blockers |
readiness blockers | fix what the blocker names |
403 approval_intent_required, approval_intent_mismatch, 410 approval_intent_expired |
the approval proof is missing, stale or old | mint a new intent and confirm again |
403 step_up_required, 410 step_up_expired |
the user must confirm with Payroo | the component handles it |