Skip to main content
The Recurring line items API manages payments and deductions that repeat across pay runs — a season ticket loan repayment, a regular allowance, a fixed monthly deduction. You create an item once against an employee and a pay element, and the service applies it to each pay period until it ends, tracking exactly what was taken, what fell short, and why any period was skipped. Use it when you need to automate ongoing pay adjustments instead of adding one-off line items to every pay run by hand. The service is available at /v1/recurring-line-items under the gateway base URLs listed in the API reference introduction.

​
Key concepts

  • Recurring line item — a repeating payment or deduction attached to one employee via a pay element. It carries the amount per period, a start date and optional end date, and a status: Active, Suspended, Cancelled, or Completed.
  • Mode — how the item decides when to stop. DateRange items run between their start and end dates. Balance items deduct an amount per period against a balance target — the response tracks the opening balance, the amount settled to date, and the balance remaining.
  • Period — the record of the item’s application to a single pay period. A period is addressed by tax year and sequence, and captures the original value, the amount actually deducted, any shortfall, and a status: Pending, Paid, PartiallyPaid, or Skipped.
  • Skip — a period that was not applied. Every skipped period records a reason code, whether you skipped it manually or the service skipped it — for example insufficient net pay, the protected earnings limit, or a paused schedule.
  • Shortfall behaviour — what happens when the full amount cannot be taken in a period: Skip drops the difference, CarryForward adds it to later periods, capped by an optional carry cap multiplier. The item’s response reports the accumulated shortfall.
  • Protected earnings — an optional floor on the employee’s pay. When a deduction would breach it, the period records a ProtectedEarningsLimit skip reason.

​
API structure

All paths below are relative to the service base path.

​
Recurring line items

Create an item with POST /, supplying the employee, pay element, mode, dates, and amounts. List an organisation’s items with GET /, filtering by status and mode, or list one employee’s items with GET /employees/{employeeId}. Fetch a single item with GET /{id}.

​
Item updates

PATCH /{id}/employees/{employeeId} updates an item in place — change amounts, dates, or shortfall behaviour, or move the item between statuses to suspend, resume, cancel, or complete it. DELETE /{id}/employees/{employeeId} removes the item.

​
Periods

GET /{id}/employees/{employeeId}/tax-years lists the tax years an item has periods in. GET /{id}/employees/{employeeId}/periods lists the periods, optionally filtered by taxYear. PATCH /{id}/employees/{employeeId}/periods/{taxYear}/{sequence} overrides the amount for one period, and the matching DELETE skips that period.

​
Typical workflow

  1. Create a recurring line item with POST / — pick DateRange for a fixed run of dates, or Balance with a balance target for a loan-style deduction.
  2. Process payroll as normal — see Running a pay run. Each pay period the item covers is recorded with the amount taken and any shortfall.
  3. Review progress with GET /{id}/employees/{employeeId}/periods, using GET .../tax-years to find which tax years to query.
  4. Adjust a single upcoming period with the period PATCH (change its amount) or the period DELETE (skip it) — the item itself is untouched.
  5. Change the item’s amounts or dates, or suspend and later reactivate it, with PATCH /{id}/employees/{employeeId}. Balance items complete on their own once the balance remaining reaches zero.

​
Notes and best practices

  • List endpoints paginate with pageSize and paginationToken — pass the token from one response into the next request.
  • A period PATCH accepts only an amount and affects that period alone; to change every future period, update amountPerPeriod on the item instead.
  • Skipped periods keep their skip reason code, so you can tell a manual skip apart from one caused by insufficient net pay or protected earnings.
  • For Balance items, watch balanceRemaining and amountSettledToDate on the item rather than summing periods yourself.

​
Authentication

Every request needs an X-Auth-Token header, and credentials with access to more than one organisation also send X-Org-Id — see Authentication. Responses use the shared envelope described in Response format.