Payroll

Read RTI payroll periods and payslips, and mark HMRC liability payments as paid or unpaid.

   
SDK service client.Payroll (PayrollService)
FreeAgent docs dev.freeagent.com/docs/payroll
Sample app /payroll (tax year), /payroll/period (payslips)

Minimum access level: Tax and Limited Accounting. UK payroll companies only.

Methods

ListAsync

Task<PayrollTaxYear> ListAsync(int taxYearEnd, CancellationToken cancellationToken = default)

HTTP: GET /v2/payroll/:year

Returns periods and payments for the tax year end (for example 2026 for April 2025–March 2026).


ListPayslipsAsync

Task<PayrollPeriod> ListPayslipsAsync(
    int taxYearEnd,
    int periodNumber,
    CancellationToken cancellationToken = default)

HTTP: GET /v2/payroll/:year/:period

periodNumber is the pay period index within the tax year (0–11).


MarkPaymentAsPaidAsync

Task<PayrollTaxYear> MarkPaymentAsPaidAsync(
    int taxYearEnd,
    DateOnly paymentDate,
    CancellationToken cancellationToken = default)

HTTP: PUT /v2/payroll/:year/payments/:payment_date/mark_as_paid


MarkPaymentAsUnpaidAsync

Task<PayrollTaxYear> MarkPaymentAsUnpaidAsync(
    int taxYearEnd,
    DateOnly paymentDate,
    CancellationToken cancellationToken = default)

HTTP: GET /v2/payroll/:year/payments/:payment_date/mark_as_unpaid


Models

Type Role
PayrollTaxYear Tax year envelope with Periods and Payments
PayrollPeriod Period metadata and optional Payslips
PayrollPayslip Per-user payslip amounts
PayrollPayment Liability payment due date, amount, and status
PayrollPeriodFilingStatus Period filing status (unfiled, pending, rejected, partially_filed, filed)
PayrollPaymentStatus Payment status (unpaid, marked_as_paid, paid)
PayrollNiCalculationType NI calculation method (Director, Employee)
PayrollStudentLoanDeductionsPlan Student loan plan (Plan 1, Plan 2)

Payslip user links deserialize to UserId / nested User using the standard expandable user pattern.

Sample

var taxYearEnd = 2026;
var taxYear = await client.Payroll.ListAsync(taxYearEnd);

var period = await client.Payroll.ListPayslipsAsync(taxYearEnd, 0);
foreach (var payslip in period.Payslips ?? [])
{
    Console.WriteLine($"{payslip.UserId}: {payslip.BasicPay}");
}

// Liability payments are keyed by due date. Pick an unpaid payment that aligns with
// a completed pay period (see console smoke: PayrollLiabilityPaymentProbeSupport).

The console --run-all example loads payslips per period and only marks a previous period’s liability when at least two periods have payslips. See Smoke and test limitations.


Copyright © Mark Heydon. Distributed under the MIT licence.

This site uses Just the Docs, a documentation theme for Jekyll.