Write-back · guide

How to Write Benefits Deductions Back into Payroll After Enrollment

After enrollment closes you turn each employee's elections into deduction lines and post them to the employer's payroll system against the employer's own deduction codes, but only some integration vendors support that write and each only on a specific list of payroll systems: Bindbee, Knit, Finch and Unified.to offer it to differing degrees, while Merge, Kombo and Apideck don't document deduction write.

By Eli Wilson · Published 2026-10-01

Short answer: after enrollment closes, you turn each employee’s elections into deduction lines and post them to the employer’s payroll system against the employer’s own deduction codes. Only some integration vendors support this write, and each on a specific list of payroll systems. Bindbee exposes it as POST /employee-payroll-runs (Supported), where each write targets one pay period or payroll run. Knit documents enroll, update and unenroll endpoints for an employee deduction on ADP Run, ADP Workforce Now, Paycor, Paychex, Paylocity, PrismHR, Avionte and QuickBooks Payroll (update and unenroll on a subset). Finch sells it as a Deductions product on its Pro plan. Unified.to has a deduction write endpoint, but among the US payroll systems checked only Paylocity lists it. Merge, Kombo and Apideck don’t document deduction write.

Whichever vendor you use, the steps are the same: read the per-connector requirements, map each plan to the customer’s payroll code, send each write so a retry can’t double-post, then read the result back to confirm it landed in the period you intended. The worked example below uses Bindbee’s endpoints because its docs publish per-connector request bodies; check the equivalent calls with any other vendor.

Which vendors can write deductions at all

As of 1 Oct 2026, from each vendor’s public pages:

Deduction write by payroll system (vendors that publish per-system status)

“Not documented” for Knit means the system is not in the supported-apps list for its deduction endpoints. Bindbee’s “Beta” means built but not battle-tested, and enabled on request. Full per-system detail, including Bindbee’s other Beta systems: payroll deduction write support by payroll system.

Step by step

Step 0: Know what the employee elected

Your platform already holds the elections. If you also want to reconcile against what the HRIS holds, check what your vendor can read. Bindbee has two useful reads where the connector supports them:

• Employer Benefit: the plan catalog, including plan_name, provider_name, benefit_plan_category, payroll_codes and deduction_code. Both code fields can be empty, so treat them as a hint and still confirm with the employer.
• Benefit: one enrollment, with coverage_tier, employee_contribution, company_contribution, start_date (the election) and effective_date (the plan year). Enrollments accumulate one per plan year, so filter to the current one.

Other vendors expose this differently: Knit’s employee_deduction model carries benefit type, employee and employer contribution, frequency and start/end dates; Unified.to has a plan-level Benefit object and an employee-level Deduction object; Apideck shows benefit amounts inside payroll read. Benefits read is connector-dependent everywhere; see Bindbee’s benefits data models for its matrix.

Step 1: Read the per-connector write requirements

Each payroll system wants something different. In Bindbee, call:

GET /employee-payroll-runs/meta/post

It returns the required fields and any integration_params for that connection. Build your request from this response at runtime instead of hard-coding one body shape. With other vendors, find the equivalent schema or supported-fields reference for each connector before you write.

Step 2: Map plans to the customer’s payroll codes

In Bindbee:

GET /payroll-codes

Filter to type DEDUCTION (and EARNING if you write employer contributions as earnings). Which code maps to which plan is the customer’s decision, whichever vendor you use. Put a mapping screen in your onboarding and have the employer’s payroll admin confirm it. A wrong code puts money in the wrong bucket, and it will show up on a pay stub.

Step 3: Shape the body for the connector

The body varies by system. From Bindbee’s docs:

• Workday identifies the deduction by type + id, accepts one deduction per request, requires payroll_run: null, and rejects a body that contains both earnings and deductions.
• ADP identifies it by code.

So a Workday employee with medical, dental and vision needs three requests, while other systems may accept several lines in one.

Every Bindbee write also names the period or run it belongs to, and that differs by connector: Workday and SAP SuccessFactors take start_date and end_date, UKG Ready takes a specific payroll_run id, and ADP takes a payroll_file batch (payroll_process_name). See the create employee payroll runs reference.

Workday (one deduction per request, payroll_run must be null; IDs, codes and amounts are placeholders):

{ "employee": "<id>", "payroll_run": null, "start_date": "2026-11-01", "end_date": "2026-11-30",
  "deductions": [ { "type": "Workday_Deduction_Code", "id": "<code id>", "amount": 142.50 } ] }

ADP Workforce Now (identifies by code; several lines allowed; codes and amounts are placeholders):

{ "employee": "<id>", "deductions": [ { "code": "MED", "amount": 142.50 }, { "code": "DEN", "amount": 18.20 } ] }

The shape of the write itself also differs between vendors. Bindbee’s is a payroll-run line for one period. Knit’s endpoints are framed as enrolling an employee in a deduction, updating it and unenrolling. Unified.to’s are create and update on a Deduction record. Ask each vendor what one call does in the payroll system: one period, or an ongoing deduction until changed.

Step 4: Send with an idempotency key

Payroll writes must not double-post. Ask every vendor how retries are de-duplicated. In Bindbee, send an X-Idempotency-Key header derived from the employee and the period:

POST /employee-payroll-runs
X-Idempotency-Key: payroll-{employee_id}-{period_end}

For systems that take one deduction per request, add the payroll code to the key. A timed-out write may still have landed in the source system. Retry it with the same key and the same body, and do it promptly: Bindbee keeps the saved result for five minutes, after which the key may be treated as new. Past that window, read the run back before retrying. A 409 means either the first attempt is still in progress (wait and retry the same key) or the body changed (a genuinely new write needs a new key). See idempotency and idempotency and payroll cut-offs for deduction writes.

Step 5: Handle the response, then read it back

In Bindbee, a write goes straight to the payroll system and returns that system’s response. It is not readable through GET until the next sync, which is every 24 hours by default; force a resync if you need to confirm sooner (resync connector). Then read the run and check start_date, end_date and check_date. With a pass-through vendor such as Unified.to, a read goes to the source directly, but you still need to read back.

This check matters because payroll periods close. A write that arrives after the employer’s cut-off can land in the next open period. Bindbee does not expose the cut-off through the API; whether other vendors do was not verified for this article. Ask each employer for their processing calendar, write well ahead of it, and flag any run that lands in a different period than you intended. On Finch assisted connections, allow for write-back taking up to 2 business days.

Step 6: Changes mid-year

How you change or stop a deduction depends on the vendor’s write model:

• Bindbee: there is no PATCH, and nothing standing to edit; each write covers one pay period or payroll run. Write the new amount from the first period the change takes effect, and stop writing it from the next period when coverage ends. Whether a second write with the same code in the same period adds to or replaces the first is not documented, so read the run back. Any new line needs a key that identifies the change, for example payroll-{employee_id}-{period_end}-{code}-v2; reusing the original key with a different body returns 409.
• Knit: documents an update-employee-deduction endpoint (ADP Run, ADP WFN, Paycor, Paychex, Paylocity) and an unenroll endpoint (the same five plus QuickBooks Payroll). On PrismHR and Avionte, only enroll is listed.
• Unified.to: documents Update a deduction; among US payroll systems checked, Paylocity is the one that lists it.

Keep your own ledger of what you sent per employee per period, whichever vendor you use. It is your source of truth for what payroll should show.

Limits by vendor

Bindbee

• Write: Supported. BambooHR, Rippling, Paycom (API), Personio, TriNet and others can’t receive deduction writes. Gusto is not in Bindbee’s integration list.
• No edits: no PATCH/PUT for deductions, employees or compensation.
• No standing elections. Each write covers one pay period or payroll run; your system owns the per-period schedule.
• No compensation write. Passthrough to the vendor API is the only route, where the vendor allows it (passthrough).
• Benefits models are read-only, so you write the payroll deduction, not the enrollment.
• Cut-offs are invisible; read back and reconcile.
• Write requires Pro or above. Basic is read-only and covers only the Employee model.

Merge

• Deduction write is not documented in Merge’s HRIS common models as of 1 Oct 2026. Documented HRIS writes are Employees and Time Off.

Finch

• Deduction write is a Pro plan product marked “Employer Fee Required”; Pro pricing is not published.
• On assisted connections, changes are written back within 2 business days, so leave room before each payroll cut-off.
• Per-provider deduction coverage was not verified here; check it per provider.

Kombo

• No deduction write path in Kombo’s OpenAPI. Payroll read (pay runs, payslips) lists UKG Pro and UKG Ready only.

Apideck

• No deduction or contribution write; payroll is read-only. No benefits or enrollment model.

Knit

• Enrollment write is documented on eight systems; update on five; unenroll on six. Workday appears only for company-wide deduction create.
• Not documented for UKG, Dayforce, SAP SuccessFactors, Rippling, BambooHR or Gusto (Knit marketing pages list deduction endpoints for some apps its docs don’t; rely on the docs lists).
• No benefits plan or enrollment model; benefits appear as deductions.

Unified.to

• Among the US payroll systems checked, only Paylocity lists deduction create/update. ADP WFN, Paycor and UKG Ready list read only; Paychex and UKG Pro list read and remove; Workday, Rippling, BambooHR, Dayforce and Paycom have no Deduction object.
• Unsupported operations return 501, so test each connector before relying on it.

Frequently asked

Can I update an existing deduction?

It depends on the vendor. Not through Bindbee: there is no update endpoint, so a change is the new amount written for the next period. Knit documents an update endpoint on ADP Run, ADP WFN, Paycor, Paychex and Paylocity. Unified.to documents one; among US systems checked, Paylocity lists it.

How do I stop a deduction?

In Bindbee, stop writing it; nothing carries into the next period unless you write it. Knit documents an unenroll endpoint on ADP Run, ADP WFN, Paycor, Paychex, Paylocity and QuickBooks Payroll. Unified.to lists "remove" on Paylocity, Paychex and UKG Pro.

Source limits

Sources checked

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