> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowpayroll.ai/llms.txt > Use this file to discover all available pages before exploring further. # Statutory pay API overview > Calculate, record, and manage UK statutory payments — SSP, SMP, SPP, SAP, ShPP, parental bereavement, and neonatal care pay — for your employees. 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](/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](/guides/pay-runs/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. For how statutory payments behave in the product, including how they appear in pay runs, see the [statutory payments guide](/guides/compliance/statutory-payments). ## Authentication Every request needs an `X-Auth-Token` header, and multi-organisation credentials must also send `X-Org-Id` — see [Authentication](/api-reference/authentication). Responses use the shared envelope described in [Response format](/api-reference/response-format).