Approve Payroll
Approve a payrun for GB employees.
This endpoint approves the payrun and updates GB-specific cumulative values (YTD gross, tax, taxable pay, allowances, and pension contributions).
Both operations run within a single transaction - if cumulative values update fails, the payrun approval will be rolled back.
If any payslips have NMW compliance warnings, approval is blocked (409
PAYRUN_NMW_VIOLATIONS) unless force_approve=true acknowledges them. A force approval
needs the pay_runs:override permission (403 PERMISSION_REQUIRED otherwise) and a
non-blank force_approve_reason in the JSON body (422 INVALID_FIELD_DEPENDENCY,
params.reason REQUIRED; a reason without force_approve is refused with
params.reason NOT_ALLOWED). When it
overrides the refusal, the approval’s status version records it in
calculation_approve.force_approval: who approved and when, the reason, the refusals
overridden and the employees concerned. With nothing to override, a force approval
approves the run as any approval does and records nothing.
A payrun that is not a draft is refused with 400 PAYRUN_NOT_IN_DRAFT_STATUS, or 400 PAYRUN_STILL_PROCESSING while it is being calculated.
Approval is rejected (409 UNFINISHED_PAYRUN) while another approved payrun that pays an employee of this one has not yet succeeded, and (409 HMRC_CREDENTIALS_NOT_CONFIGURED) while the organization has no HMRC credentials.
Approval is refused (422) when an employee’s first FPS would carry a starter block HMRC rejects, or when the FPS would carry more than 4 NI letters, a Freeport or Investment Zone letter without the workplace postcode, or SMP for an off-payroll worker, or when an employee’s off-payroll status or the NI letter of an earlier payment changed after that payment was approved.
The runs of a pay calendar and pay group are approved in the order they pay, and so is
a supplementary run of another of the pay group’s calendars, which can pay after the
next calendar’s main run (409 EARLIER_RUN_NOT_APPROVED while such an earlier-paying run
is neither approved nor cancelled; params.run_ids lists them, earliest first, and
params.id names the one to approve or cancel next, params.created_by who created
it). A supplementary run is refused
once its payment date has passed (422 VALUE_OUT_OF_RANGE, params.reason IN_PAST),
and when the supplementary date rules no longer allow its date for its pay calendar
as it stands, after the calendar’s dates or the rules changed (422 VALUE_OUT_OF_RANGE,
params.reason OUTSIDE_TAX_PERIOD, OUTSIDE_PAY_PERIOD or CALENDAR_DATE; cancel it
and create one on an allowed date). A run that would pay nobody is refused
(409 INVALID_TRANSITION, params.reason NO_EMPLOYEES): a supplementary run nobody
holds pay items in, or a positive pay main run none of whose
own pay group members holds pay items in it; its calculation_approve task stays
DRAFT, not ready. pay_nobody=true approves such a main run anyway, without a
calculation; it does not lift the refusal for a supplementary run. A net change main
run pays its members’ standing pay without pay items, so the flag never applies to it.
A main run whose pay group has no member it pays (none, or supplementary runs pay them
all) is approved without the flag.
An approved run that pays nobody (no payslips) files no FPS and produces no payment file, and
nothing else is sent to HMRC for it: report a tax month on the EPS as without payments yourself,
and only if you paid nobody in it, in any pay group or run. Its hmrc_fps_submission and
bacs_file_generation tasks are SUCCESS with skipped_reason NO_PAYSLIPS; an organization
without a BACS service user number gets no BACS task, as for its other runs.
Approval is refused (409
RESULT_NOT_CALCULATED, params.reason STALE) for employees whose payslip was
calculated before another of their payments this tax year was approved or removed (its
ledger basis below or above the current one), or without the deduction figures:
calculate the run again for them. Approval is refused the same way (params.reason
OUTSIDE_RUN) for payslips or pay items of employees the run no longer pays, such as one
calculated before the run’s ownership rules changed: calculate the whole run again,
without employee_ids, which deletes their payslips and salary and statutory pay
items; delete first the pay items of an employee no longer in the pay group. Every
employee the run pays
needs a payslip (400 PAYRUN_MISSING_PAYSLIPS): those holding pay items in it and, for a
MAIN run of a net change pay group, the members of its pay group that no supplementary
run of the period pays instead.
Query Parameters
Positive pay only: approve a main run that would pay nobody, because none of its pay group members holds pay items in it. Without it such a run is refused (409 INVALID_TRANSITION, params.reason NO_EMPLOYEES). A net change main run pays its members' standing pay without pay items, so it never needs this. It does not lift the refusal for a supplementary run, and changes nothing for a run that pays somebody.
Body
The optional body of an approval.