> ## 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.

# Recurring line items API overview

> Set up recurring payments and deductions for employees, then track and adjust the amount taken in each pay period.

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](/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](/guides/pay-runs/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](/api-reference/authentication). Responses use the shared
envelope described in [Response format](/api-reference/response-format).