Run payroll each period

Once the employer has completed onboarding, PayrollKit opens each scheduled Pay Run automatically. Send the approved earnings and payment arrangements, then open PayrollKit so the employer can review and approve it.

Some tips before you start

Use your server-side PayrollKit access token to authenticate all API requests.
Include an Idempotency-Key with every request that creates or changes data.
Keep a stable ID for each earning you send. Include your product's version and the employer's approval time with each set of Pay Run inputs. See the API reference for the exact fields and formats.
You can save returned PayrollKit IDs to avoid lookup calls.
An ETag identifies the version of a PayrollKit record you last retrieved. When updating that record, send its ETag in the If-Match header so PayrollKit can stop you from overwriting a newer change. If you did not keep it, retrieve the record again before updating it.

End to end guide

Find and check the Pay Run

PayrollKit opens Pay Runs automatically. Call GET /employers/{employerId}/pay-runs to find Pay Runs that have not been approved, then save the relevant Pay Run ID.
Call GET /employers/{employerId}/pay-runs/{payRunId}/checks.
Confirm the expected employees and resolve any issues that prevent calculation.

Send the approved payroll information

Call PUT /employers/{employerId}/pay-runs/{payRunId}/inputs with all approved pay lines and payment arrangements, including the submission version and approval time.
Send the complete set of inputs, not just the changes. An accepted request creates the next immutable Pay Run Input Revision, so anything left out is absent from the new current revision. If any item is invalid, PayrollKit saves none of the request.

Review and approve in PayrollKit

Create an embedded session for this page, then open the Pay Run:

<PayrollKit
  sessionToken={session.sessionToken}
  initialView={{ view: "PAY_RUN", payRunId }}
  onSessionEnded={({ reason }) => handleSessionEnd(reason)}
/>

PayrollKit guides the employer through missing information, review and approval.

What happens after approval

When the approved Pay Run has reportable results, PayrollKit creates and submits the FPS to HMRC automatically. A Pay Run containing only all-zero results does not create a Filing. PayrollKit also emails Payslips to employees and lets employers create the files they need for accounting, pension submissions and bank payments.
Employers can follow progress, respond to any actions, and view or download everything in the component. To show the same information in your own product, use the API reference and signed webhooks.
PayrollKit automatically opens the next Pay Run for the schedule, ready for the next pay period.

Onboard an employer

Keep data in sync