Court orders API overview

The Court orders API manages attachment of earnings orders against an employee’s pay: Child Maintenance Service deductions from earnings (CMS DEO), priority and non-priority attachment of earnings orders (AEO), direct earnings attachments (DEA), council tax attachment of earnings orders (CTAEO), and the Ea and Mcaeo order types. You create an order once with its deduction basis and protected earnings rules, and each pay run then records the deduction taken as a line item on the order. Use this API when an employer receives an order from a court, the CMS, HMRC, or a local authority and needs it applied through payroll. All paths on this page are relative to the service base path /v1/court-orders, which you append to the environment base URLs listed in the API reference introduction.

​

Key concepts

• Order type — every order is one of seven types: CmsDeo, AeoPriority, AeoNonPriority, Dea, Ctaeo, Ea, or Mcaeo. The type is the discriminator on create requests and responses, and determines which type-specific details the order carries (for example, a DEA’s rate table and combined cap, or a CTAEO’s local authority and jurisdiction).
• Deduction basis — how the deduction is calculated each period: Table (statutory deduction tables), Percentage, or FixedAmount. Table-based orders name a tableType; the tables themselves are published through the reference data endpoints.
• Priority level — orders are ranked for processing as Cms, PriorityOrders, NonPriority, or StudentLoans, and each order reports whether it is a priority order. An order’s studentLoanInteraction setting controls whether student loan deductions run normally, are suppressed while the order is active, or are restricted by protected earnings.
• Protected earnings — the portion of pay an order cannot touch. Each order carries a protectedEarningsSetting (None, CourtPerAmount, SixtyPercentOfNet, or TableImplied) and, where relevant, a protected earnings amount. When a deduction is reduced to respect protected earnings, the shortfall is carried forward on the order.
• Payee — the body the deductions are remitted to, held once per organisation and referenced from orders by payeeId. A payee has a payment method (Bacs, Cheque, or Card) and, for Bacs, account details. Orders also carry a remittanceReference and a remittance deadline of FiveDays or NineteenthOfFollowingMonth.
• Line item — the record of one pay run’s deduction against an order: the expected deduction, the amount paid, the remaining value, whether protected earnings reduced it, and a status of Pending, Paid, PartiallyPaid, or Discharged.
• Order status — an order is Active, Suspended, OnHoldNoEligibleEarnings, or Discharged. Total-debt orders track totalAmountOwed, previouslyPaid, amountRepaidToDate, and remainingBalance.
• Admin fee — an order can flag adminFeeApplied to charge the employee the statutory administration fee; the fee amount is published in the reference data constants.

​

API structure

​

Court orders

Create, retrieve, update, and delete orders, and list them with filters for status, order type, priority level, start date and date received ranges, issuing authority, and reference. POST /orders takes a polymorphic request keyed on orderType; GET /orders returns a paginated list driven by limit and paginationToken. GET /orders/employees/{employeeId} lists one employee’s orders with the same filters plus an optional payDate, and POST /orders/reconcile reconciles court order deductions against a pay run, optionally scoped to one employee.

​

Payees

Manage the remittance destinations for deductions. POST /payees, GET /payees, GET /payees/{payeeId}, PUT /payees/{payeeId}, and DELETE /payees/{payeeId} cover the full lifecycle; orders reference a payee by ID.

​

Attachments

Attach supporting documents — the order paperwork itself, for example — to an order. POST /orders/{orderId}/attachments registers each file’s name, content type, and size and returns a time-limited upload URL per file; DELETE /orders/{orderId}/attachments/{attachmentId} removes one.

​

Reference data

Read-only statutory constants. GET /orders/constants/available-years lists the tax years with published constants, and GET /orders/constants/{taxYear} returns that year’s values: global figures such as the protected earnings percentage, admin fee amount, remittance days, and notice periods, plus per-order-type deduction tables and bands for CMS DEO, DEA, CTAEO, AEO, and EA orders.

​

Typical workflow

1. Call GET /orders/constants/available-years, then GET /orders/constants/{taxYear}, to see the deduction tables and statutory figures that apply.
2. Create the payee the deductions will be remitted to with POST /payees, or pick an existing one from GET /payees.
3. Create the order with POST /orders, setting the orderType, the employee, the reference and issuing authority from the paperwork, the deduction basis, protected earnings, and the payeeId and remittanceReference.
4. Upload the order paperwork through POST /orders/{orderId}/attachments using the returned upload URLs.
5. Run payroll as normal — see Running a pay run. Each pay run adds a line item to the order recording the deduction taken.
6. Track progress with GET /orders/{orderId} or GET /orders/employees/{employeeId}, and use POST /orders/reconcile to reconcile deductions against a pay run.
7. When circumstances change, amend the order with PUT /orders/{orderId} — for example, to suspend or discharge it.

​

Notes and best practices

• Create and update requests are polymorphic on orderType. Send only the detail fields that belong to that type; the request schema for each type documents which apply.
• Upload URLs returned when you register attachments expire — check expiresAt and upload promptly, re-registering the file if the URL lapses.
• List endpoints are cursor-paginated. Pass the paginationToken from each response back on the next request until hasMorePages is false.
• Reference data is per tax year. Fetch the constants for the year you are processing rather than caching a single year’s values.

​

Authentication

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