Statutory pay API overview

The Statutory pay API calculates and manages the UK statutory payments an employer must make: statutory sick pay (SSP), statutory maternity pay (SMP), statutory paternity pay (SPP), statutory adoption pay (SAP), statutory shared parental pay (ShPP), statutory parental bereavement pay, and statutory neonatal care pay. You preview a calculation, create the payment for an employee, and the API produces a week-by-week schedule of line items that flow into pay runs. The service lives at /v1/statutory-pay under the gateway base URLs documented in the API reference introduction. All endpoint paths on this page are relative to that base path.

​

Key concepts

• Statutory payment — a single award of one statutory pay type for one employee, identified by a statutoryPayId. It carries the start and end dates, the total amount, a daily breakdown, its line items, and a status of Pending, InProgress, or Paid.
• Average weekly earnings (AWE) — the earnings figure a calculation is based on, derived from the employee’s payslips over the relevant period. You can supply an averageEarningsOverride when the derived figure is not appropriate.
• Line item — one payable slice of the schedule, tied to a pay period. Each line item records its source (PayrollRun, ImportedFromPreviousProvider, or ExternalDirectPayment), whether it was manually adjusted, and the adjustment reason.
• Sickness linking — SSP periods that fall close together link into one chain. The linking check reports whether a new absence links to earlier ones, the remaining SSP weeks, and whether waiting days are skipped.
• Alabaster recalculation — when an employee receives a pay rise that falls in the relevant period, AWE must be recalculated. The API detects affected payments and recalculates or updates their line items.
• External payment — a statutory amount already paid outside the payroll, recorded against the payment so the schedule reflects what remains to pay.
• Statutory rates — the HMRC weekly rates, waiting days, earnings limits, and recovery rates for a given tax year.

​

API structure

​

Statutory calculations

Preview a calculation without saving it via POST /calculations/preview, or run and store one for an employee with POST /calculations/employees/{employeeId}. Check SSP linking with POST /calculations/employees/{employeeId}/linking and review past calculations with GET /calculations/employees/{employeeId}/history. The request body is discriminated by statutoryType, so each pay type takes its own fields (for example qualifyingEventDate or neonatal care dates).

​

Statutory payments

Create a payment with POST /payments/employees/{employeeId}, then retrieve, update, or delete it at /payments/employees/{employeeId}/{statutoryPayId}. List an employee’s payments with GET /payments/employees/{employeeId} or every payment in the organisation with GET /payments/organisations — both filter by status and statutoryPayType and paginate with pageSize and paginationToken. Each payment keeps a change history at GET /payments/employees/{employeeId}/{statutoryPayId}/history.

​

Line items and schedule

List a payment’s line items with GET /payments/employees/{employeeId}/{statutoryPayId}/line-items. Override a single week with PATCH .../weeks/{weekNumber} or an individual line item with PATCH .../line-items/{lineItemSequence}, supplying the new amount and a reason. Export the full schedule with GET .../schedule/export, choosing the output with the format query parameter.

​

External payments

Record an amount paid outside the payroll with POST /payments/employees/{employeeId}/{statutoryPayId}/external-payments, including the gross and net amounts, payment date, tax year, and period. List recorded payments with GET, and remove one with DELETE .../external-payments/{lineItemSequence}.

​

Attachments

Attach supporting documents — for example a fit note or MATB1 — to a payment with POST /payments/employees/{employeeId}/{statutoryPayId}/attachments, list them with GET, and remove one with DELETE .../attachments/{attachmentId}.

​

Alabaster and earnings

Fetch the AWE calculation for an employee with GET /payments/calculations/employees/{employeeId}/average-earnings, passing the startDate of the absence. For a specific payment, GET .../alabaster-detection reports whether a pay rise affects it; POST .../alabaster-recalculate reruns the calculation and POST .../alabaster-update-line-items applies the result to the schedule.

​

Import and reconcile

Bring in payments that started under a previous payroll provider with POST /payments/import/{employeeId}, supplying the AWE, the weeks already paid, and type-specific details. POST /payments/reconcile reconciles an employee’s statutory payments against the pay run.

​

Statutory rates

GET /statutory-rates/available-years lists the tax years with published rates, and GET /statutory-rates/{taxYear} returns that year’s weekly rates, SSP waiting days, lower earnings limit, recovery rates, and the small employer threshold.

​

Typical workflow

1. Fetch the current rates with GET /statutory-rates/{taxYear} to understand the limits that apply.
2. For SSP, run the linking check to see whether the absence links to earlier sickness and whether waiting days are skipped.
3. Preview the calculation with POST /calculations/preview and review the weekly breakdown and any warnings.
4. Create the payment with POST /payments/employees/{employeeId}.
5. Inspect the line items and adjust individual weeks if needed, giving a reason for each override.
6. Let the schedule flow into your pay runs — see Running a pay run — and record any amounts paid outside payroll as external payments.
7. After a back-dated pay rise, run Alabaster detection and recalculate affected payments.

​

Notes and best practices

• Prefer the preview endpoint while integrating: it returns the same calculation output without creating a record.
• The organisation and employee list endpoints are paginated — follow paginationToken rather than assuming a single page.
• Manual overrides of weeks and line items require a reason, and the payment’s history endpoint records every change, so use them instead of deleting and recreating payments.
• Only set averageEarningsOverride when the payslip-derived AWE is wrong for the employee; clear it again with clearAverageEarningsOverride on update.

​

Authentication

Every request needs an X-Auth-Token header, and multi-organisation credentials must also send X-Org-Id — see Authentication. Responses use the shared envelope described in Response format.