Skip to main content
The Court orders API manages court orders against an employee’s pay: the Child Maintenance Service’s deduction from earnings order (DEO), the DWP’s Direct Earnings Attachment (DEA), attachment of earnings orders (AEO) as priority and non-priority orders, the magistrates’ court attachment of earnings order (MCAEO), the council tax attachment of earnings order (CTAEO), the Scottish earnings arrestment (EA), current maintenance arrestment (CMA) and conjoined arrestment order (CAO), and the attachment of earnings orders (Northern Ireland) for fines and from the Enforcement of Judgments Office. 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 Child Maintenance Service, the DWP, a council or the Enforcement of Judgments Office 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 eleven types: 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 and first pay date, a CTAEO’s local authority and jurisdiction, a CMA’s dailyRate, or an NI AEO EJO’s normalDeductionRate, protectedEarningsRate and ratePeriod). The type cannot be changed after the order is created.
  • Deduction basis: how the deduction is calculated each period: Table (statutory deduction tables), Percentage, or FixedAmount. The table follows the employee’s pay frequency, so you can leave it out; the tables themselves are published through the reference data endpoints. An AEO for maintenance or a civil debt uses FixedAmount (the court’s normal deduction rate, NDR) with protectedEarningsSetting CourtPerAmount (the court’s protected earnings rate, PER), as the Attachment of Earnings Act 1971 s6(5) sets; Table is for fines. A CTAEO, EA, CMA, CAO and both Northern Ireland orders are always Table, and a DEA’s basis follows its rateType: leave deductionBasis out for those.
  • 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, NineteenthOfFollowingMonth, AsSoonAsReasonablyPracticable (CMA) or AsTheOrderRequires (CAO and NI AEO EJO).
  • 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. An order is discharged automatically when its balance reaches zero, or when its endDate has passed with no pay period left before it. Total-debt orders track totalAmountOwed, previouslyPaid, amountRepaidToDate, and remainingBalance.
  • Pay days the order records: read-only dates kept up to date by each pay run: lastDeductionPayDate on a CMA or CAO (the next deduction counts the days since it), lastPayDate on an NI AEO EJO (the next deduction covers the time since it), and firstPayDate on a DEA.
  • 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, such as the order paperwork itself, 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 DEO, DEA, CTAEO, AEO, EA and Northern Ireland fines orders, and the protected earnings per day for a CMA.

​
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, or to record a court or DWP variation.

​
Notes and best practices

  • Create requests are polymorphic on orderType. Send only the detail fields that belong to that type; the request schema for each type documents which apply.
  • PUT /orders/{orderId} records a court or DWP variation through the type’s own fields: percentage or fixedAmount (DEO), fixedAmount, deductionBasis and the protected earnings (AEOs and MCAEO), rateType and fixedAmount (DEA), dailyRate (CMA), ordinaryDebtAmount and maintenanceDailyRate (CAO), agreedHigherRatePercentage (NI AEO fines), and normalDeductionRate, protectedEarningsRate and ratePeriod (NI AEO EJO). Only the fields you send change. A field that belongs to another order type is refused with a 400, and instructionAmount is not accepted for a CMA, CAO or either Northern Ireland order.
  • Some orders depend on the employee’s other orders. Only one CMA can run for an employee at a time, and a CAO can only be created once the employee’s earnings arrestment and CMA have ended. Each is refused with a 400 that says what to do.
  • percentageRate on a DEO (CmsDeo) request is deprecated as input in favour of percentage. It stops being accepted as input on 4 January 2027 and keeps being returned on responses. See Deprecations.
  • 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.
For how court orders behave in the product, including priority ordering across multiple orders, protected earnings in practice and how each order type is worked out, read the court orders guide.

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