Payroll API Capability Matrix · Deduction detail

Deduction write detail

What actually happens when your product pushes a deduction into payroll — for benefits, HSA/FSA and 401(k) builders who need an election to land correctly, not just to land.

The capability matrix answers “can you write a deduction at all?”. This page answers the ten questions that decide whether the write is right: whether it is taxed correctly, whether the number means dollars or a percent, which pay period it hits. Of 220 answers across 22 payroll systems and unified APIs, 100 (45.5%) are unverified because no vendor documents the behaviour.

Almost nobody can assert tax treatment on the write

Of the systems where we could read a write contract at all, only Gusto exposes tax treatment as readable state — pretax, posttax and imputed booleans per benefit type. Paylocity has no pre-tax field on DeductionCodeDto at all; treatment is a property of the company-level detType, so the write selects a code someone already classified. ADP restricts the API to two categories and requires a paper authorization form before a pre-tax code exists. Finch carries the distinction in the type name (custom_pre_tax versus custom_post_tax) rather than as a flag.

The practical consequence: for most of these systems, a benefits platform cannot guarantee through the API that a deduction it just wrote will be treated pre-tax. It can only pick a code and trust the configuration behind it.

The unit is not always in the payload

ADP Workforce Now carries amount and percent in one field, deductionRate/rateValue, and resolves which is meant from whether the deduction code number falls between 81 and 96. The field that would disambiguate it, unitCode, is marked Not Displayed. Finch is explicit but changes unit with type: cents when fixed, basis points when percent — correct, documented, and a factor-of-100 error if you assume one.

“Unified” is not always unified

Bindbee writes deductions through its employee-payroll-run endpoint, but the documented shape differs per provider: ADP takes {code, amount}, UKG Ready takes {name, employee_deduction, company_deduction}, SAP SuccessFactors takes {name, employee_deduction}. The caller still has to know which payroll system is behind the abstraction. Merge, meanwhile, documents no benefit or deduction write at all in its benefits reference, and compresses every deduction type a payroll system distinguishes into a five-value benefit_plan_type enum.

Where the unglamorous method wins

Grade C — SFTP and file drops — genuinely beats an API for correcting deductions across hundreds of employees at once, where per-employee API calls mean hundreds of requests, partial-failure handling and no atomicity. We grade it below API access for security and latency, and we say plainly that it is the better tool for bulk correction. What is not defensible is grade D: an “assisted” write, where a human with administrator credentials performs the change against a two-business-day SLA, sold in the same column as a real API write.

2 of these systems publish nothing at field level

2 of the 22 entries assessed have an entirely unverified record: isolved People Cloud, Paycom. In each case the specification is behind a login, a partnership, or an NDA, or does not exist publicly at all. A buyer cannot read the data contract before signing — which is the structural condition this publication exists because of.