Codes · reference

Every ADP client we onboard has different deduction codes — is there any standard at all?

No, and there is no partial standard either: ADP and Paylocity both let each company invent its own codes, so the only reliable move is to read the employer's code list from the API at onboarding rather than mapping to anything you expect to recur.

By Eli Wilson · Published 2026-09-10

There is no standard. Not a weak one, not a partial one — deduction codes are tenant configuration on the two largest systems whose contracts are readable, and the vendors say so in their own documentation.

Two opposite designs

Company-defined, in the vendors’ own words

Paylocity states that each company ID creates its own custom definitions of earning and deduction codes. Codes fall into category D, E or T — deduction, earning or tax — and pair with a detType that determines how payroll treats the amount. There are 40 standard deduction types and 26 earning types available, but which codes a given employer has, and what they call them, is that employer’s own configuration.

ADP is the same shape with a sharper edge: your consumer application must validate the deduction code against /meta/data/transforms/payrollInstruction/generalDeductionInstruction/deductionCode/codeList before building the payload for a write. And that codelist has a documented hole — known issue US1294444 states that a newly added Post-tax code with frequency OTO does not return in the codelist, with no workaround.

So even the discovery mechanism has a gap you have to code around.

Vendor-fixed, and what it costs

Gusto and Finch go the other way: a closed, stable vocabulary. This is much easier to build against, and the limitation is exactly the one you would predict — you cannot express something the enum does not name. Merge shows what happens when normalisation goes too far: every deduction type a payroll system distinguishes is compressed into MEDICAL, HEALTH_SAVINGS, INSURANCE, RETIREMENT and OTHER, with the original code preserved only as a free-text deduction_code string of up to 60 characters.

Dated evidence table

The scorecard for onboarding

Apply this to every payroll system you support:

1. Is there a code-list endpoint? If not, onboarding needs a manual mapping step and a spreadsheet, and you should price that in.
2. Does the list include everything you can write to? ADP’s documented OTO gap means the answer can be no even when an endpoint exists.
3. Does the code carry tax treatment? On Paylocity the detType does. If treatment rides on the code, your mapping step is also a compliance step.
4. Can you create a code? Rarely. ADP requires a form for pre-tax; Paylocity codes are company-level configuration; Gusto gates creation per type via writable_by_application.
5. What is your behaviour on an unknown code? Decide deliberately. Failing the onboarding loudly is almost always better than writing to a default and discovering it at year end.

Frequently asked

Is there an industry code standard I am missing?

Not for deduction codes. There are standards adjacent to this problem — ASC X12 834 for benefit enrolment, for instance — but none normalises payroll deduction or earning codes across vendors. The unified API vendors build their own normalisation layer precisely because no standard exists to adopt.

Can I rely on code names being descriptive?

No. Codes are alphanumeric labels chosen by whoever configured the company, and the check-stub description is a separate field from the internal description on Paylocity. Two employers can use the same string for different plans, and the same plan can carry different codes at two employers on the same payroll system.

Source limits

Sources checked

Wrong or out of date? payrolldataspecs@gmail.com — corrections are free. How claims are scored: methodology.