Skip to main content

Payroll: How to map and edit your Deduction Codes (Demo included)

  • Updated
Payroll: How to Map and Edit Your Deduction Codes — Employee Navigator Help Center

Payroll codes are the master keys that let Employee Navigator send new, updated, and ending deductions to your payroll system as enrollments and costs change. This guide walks you through three things:

  1. How to find your codes
  2. How to map them to plans
  3. How to edit them once you're live
≡
  Table of Contents
  1. How to find your codes
  2. How to map your codes
    1. Know before you map (rules, settings, tax placement)
    2. Mapping examples (Plan Based, Coverage Level, HSA, 3rd Party)
  3. Editing codes once you're live
  4. What we don't exchange to payroll
  5. FAQs
1 Part 1

How to Find Your Codes

There are two ways payroll codes get into Employee Navigator, and which one applies to you depends entirely on your payroll partner. Start by picking your partner below.

1 Step 1 — Required before the demo

Who's your payroll partner?

Pick your partner so we can tailor the demo to your import method. API partners pull codes automatically; manual partners type them in.

✓ API Method Your codes pull in automatically

Employee Navigator pulls your codes straight from your payroll system with one click. Scroll down to launch the demo →

Payroll tab › Payroll Codes › View Codes › Vendor Payroll Codes › Refresh Codes
⚙ Manual Method You'll type in codes from a list HR provides
There's no automatic pull for this partner, so the interactive demo below does not apply to you. Skip past it to the Manual Method walkthrough — it covers exactly what you need to do. 
2Step 2 · Interactive Demo

Walk through finding and mapping your codes

Click through the real flow below. You'll find your payroll codes page, refresh codes from your partner, and map each plan to a code — all in one cohesive walkthrough. Every button works.

Find codes Open settings Refresh from partner Map each plan

Manual method walkthrough

The screens look identical to the API method above — the only difference is you type the code into the Pre-Tax or Post-Tax field instead of picking from a dropdown.

  1. Ask HR to generate their payroll system's payroll code report (each vendor has specific steps — see the partner-specific guides linked above)
  2. In EN, go to the Payroll tab → Payroll Codes card → View Codes
  3. Click the ✎ pencil next to each plan
  4. Type the code from HR's list into the Pre-Tax or Post-Tax field, then Save
2 Part 2

How to Map Your Codes

Now that your codes are loaded, it's time to map each code to the right plan in Employee Navigator. Before you map, review the three things below — rules to follow, transmission settings, and where Pre-Tax vs. Post-Tax placement matters.

 Know before you map
Three things to check before clicking Save on any plan

Rules every mapping must follow

✓
Unique codes per benefit. The same code can't be used for medical & dental, or for Accident & Critical Illness. Each benefit type needs its own code so EN can start, stop, and change deductions independently.
✓
Combined deductions won't work. If a code such as "PRE125" covers medical + dental today, then new per-category codes must be created in payroll first and mapped in EN.
!
Multiple company IDs in your payroll system? The code must exist in every company ID in payroll — otherwise EN can't transmit for employees in the companies where the code is missing.
!
100% employer-paid benefit? Set the Transmission Option to Never Send.

Transmission settings you'll see in the edit modal

The mapping modal has two sets of transmission options — one for Deductions (employee side) and one for Earnings (employer contribution).

Deduction Transmission
  • Always Send — the default. Transmits every cost, even $0.
  • Never Send — use only for 100% employer-paid benefits with zero employee cost.
Earning Transmission
  • Always Send — the default. Transmits when your partner accepts ER contributions via API.
  • Never Send — use when your partner doesn't accept ER contributions. Code can still be entered for reporting.
i
Do I need Employer Codes? Not always. If your payroll partner doesn't accept ER contributions via API, leave the "No" checkbox marked. If you want a code for reporting purposes, enter it and set Earning Transmission to Never Send.

Pre-tax vs. Post-tax placement

Taxability is determined in payroll, but where you map the code in EN matters in some scenarios. Use this table to decide which column the code goes in.

Scenario What to do
One code for all employees, configured as either pre- or post-tax in payroll Map to the respective section depending on how the code's taxability is configured in payroll
Two codes — some employees pre-tax, others post-tax Each code must go in its respective column on all applicable plans
One code, plan allows user to define tax status (e.g., Voluntary LTD/STD)
  • Post-tax only → map to Post-Tax column
  • Pre-tax only → map to Pre-Tax column
  • Both allowed → map both codes, each to its respective column
3rd Party App plan (carrier is system of record) Both Pre-Tax and Post-Tax codes are required to save
🏢 How do I configure post-tax deductions for specific employees? ›

If they are 2% shareholders or Direct lineal descendants of a 2% shareholder:

  1. Go to the employee's Profile → Employment → Statutory Class
  2. Choose 2% Shareholder and Save

EN will apply only the post-tax codes you've mapped into your payroll group(s) for this employee.

If they are NOT 2% shareholders: Create a second payroll group with the same frequency, map the post-tax codes in that group (plus any pre-tax codes for plans withheld pre-tax for everyone), then reassign these employees to the new payroll group.

Mapping examples

Plan Based is the default and handles most plans. Expand the examples below if you have Coverage Level, HSA, or 3rd Party App plans that need a different setup.

EX Plan Based Codes — the default that most customers have ›

A single code like MDCL represents the full consolidated cost — employee plus spouse plus dependents. Map the code in the applicable Pre-Tax or Post-Tax field and you're done.

When to use it: most medical, dental, and vision plans, FSAs, and similar plans where payroll handles the full cost as one line item.

Bi-weekly Static preview
Plan Name
Medical
 

Deduction Transmission Options
Always Send
Never Send
Earning Transmission Options
Always Send
Never Send
  Deduction Codes Earnings Code
Coverage Level Code Pre-Tax Code Post-Tax Code Employer Code
Employee

MDCL —

Yes No
One code covers everyone on this plan — regardless of tier. EN sends the per-pay cost using the MDCL code.
EX Coverage Level Based — when you have a separate code per tier ›
i
This is optional. Coverage Level Based is offered for flexibility — only use it if your payroll system already uses a separate code per tier. You do not need to change how your codes are configured in payroll.

Multiple codes, each representing one coverage tier's cost:

  • MEDEE — Employee only
  • MEDSP — Employee + Spouse
  • MEDCH — Employee + Child
  • MEDFAM — Family

Switch the Mapping Type dropdown from "Plan Based" to "Coverage Level Based" and the modal expands to let you map each tier independently.

Bi-weekly Static preview
Plan Name
Medical
 

Deduction Transmission Options
Always Send
Never Send
Earning Transmission Options
Always Send
Never Send
  Deduction Codes Earnings Code
Coverage Level Code Pre-Tax Code Post-Tax Code Employer Code
— for Employee

MEDEE —

Yes No
— for Employee + Spouse

MEDSP —

Yes No
— for Employee + Child

MEDCH —

Yes No
— for Family

MEDFAM —

Yes No
EN sends the code that matches the employee's enrolled tier — so a spouse-tier enrollment transmits MEDSP, not MEDEE.
!
Coverage Level Based is only available for plans with Composite rate types. It's not supported for ACA-rated, Banded, or Individually-Banded rates.
EX HSA — Limit Level based codes for single vs. family IRS maximum rules ›

HSA plans let you configure up to 4 codes: Single, Family, Single Catch-up, and Family Catch-up. If a tier isn't used, the same code can be reused across rows.

Bi-weekly Static preview
Plan Name
Health Savings Account
 

Deduction Transmission Options
Always Send
Never Send
Earning Transmission Options Locked
Always Send
Never Send
  Deduction Codes Earnings Code
Limit Level Code Pre-Tax Code Post-Tax Code Employer Code
Single

HSAS —

Yes No
Family

HSAF —

Yes No
Single Catch-up

HSAS —

Yes No
Family Catch-up

HSAF —

Yes No
Best-practice setup: the regular HSAS / HSAF codes are reused in the Catch-up rows so catch-ups are managed manually in payroll.
i
Why is Earning Transmission locked to Never Send? HSA is a Deductions only plan type — EN doesn't transmit employer contributions for HSAs (see What We Don't Exchange to Payroll). Always Send isn't selectable for this benefit.
★
Best practice: map the regular Single/Family codes into the Catch-up rows as well, and manage catch-up contributions manually in payroll. This prevents employees 55+ from having their regular deferrals capped at $1,000 if the catch-up code has an annual max set in payroll.

⚠ EN does not send two codes for an over-55 employee (regular + catch-up). It only sends the code mapped into the Catch-up rows.

EX 3rd Party App plans (Colonial, etc.) ›

The carrier is the system of record — effective dates, benefit amounts, and premiums all flow from the carrier into EN, and EN passes the mapped code + cost to payroll.

  • Coverage level isn't selectable — it's auto-configured based on the 3rd party app tie-in
  • Both a Pre-Tax and Post-Tax code are required to save
  • Each 3rd party plan needs a unique code (Accident and Critical Illness can't share the same Colonial code)
Bi-weekly Static preview
Plan Name
Colonial Accident
 

Deduction Transmission Options
Always Send
Never Send
Earning Transmission Options
Always Send
Never Send
  Deduction Codes Earnings Code
Coverage Level Code Pre-Tax Code* Post-Tax Code* Employer Code
Employee

COLPRE COLPOST

Yes No
Both COLPRE and COLPOST must be entered — the modal won't save without both codes filled in.

Editing Codes Once You're Live

Once your integration is live, codes and transmission settings can still be edited — by both brokers and HR. EN will prompt you to confirm the change and then immediately re-transmit affected deductions with their updated code(s) to your payroll partner.

In Audit Mode
  • Edit freely — codes, transmission settings, mapping type
  • No modal appears, no transmission triggered
  • Re-enter the Deduction Audit to continue resolving discrepancies after your edits
Live Integration
  • Edit a code → confirmation modal appears on Save
  • On Confirm, EN immediately transmits all affected deductions
!
Use this only to correct valid mistakes. Editing codes on a live integration should be reserved for fixing genuinely incorrect mappings — for example, the wrong code was mapped, a typo, or a code your payroll partner doesn't recognize.
3Step 3 · Live Edit Demo

See it in action — edit a live code end-to-end

Watch what happens when you edit a code on a live integration. Open the edit modal, change a code, confirm, and watch your data sync to your payroll partner in real time.

Open plan Change code Confirm Live push

What We Don't Exchange to Payroll

Fully unsupported plan types
  • Commuter Benefits
  • 401(k)
  • Universal Plans
Deductions only (no employer contributions)
  • HSA
  • Group Life
  • Group AD&D

FAQs

Q Can I edit my payroll codes once I'm live for the integration? ›

Yes — see the Editing Codes Once You're Live section above. On Save, a confirmation modal appears; once you Confirm, EN immediately re-transmits all affected deductions to payroll. If you replaced a valid code with another, HR will need to end the old code in payroll manually.

Q Can I use the same code for more than one benefit type? ›

No. Every benefit category must have a unique code. For example, Accident and Critical Illness cannot share a "Colonial Pre" code — each plan needs its own code so EN can start, change, or stop deductions independently. This also applies to Group Life vs. Voluntary Life, and to every 3rd party app plan.

Q Does it matter if a code goes in the Pre-tax or Post-tax column? ›

Sometimes. See the Pre-tax vs. Post-tax tab in the Know Before You Map module — one-code-for-everyone scenarios don't care, but any setup with pre/post variation, user-defined tax status, or 3rd party apps does.

Q Do I need Employer Codes if my payroll partner doesn't accept them via API? ›

No. Leave "No" marked under Employer Codes. If you want to enter one for reporting purposes only, set the Earning Transmission Option to Never Send — the code will be stored in EN but won't transmit.

Q For HSA plans with catch-up codes — what's the recommended setup? ›

Best practice is to map the regular Single/Family HSA codes into the Single Catch-up and Family Catch-up rows as well — then manage catch-up contributions manually in payroll. This prevents the catch-up code from capping an over-55 employee's deferrals at $1,000 if your payroll partner has an annual max on that code.

⚠ EN will not send two codes for employees over 55 (one for the regular limit + one for the catch-up). It sends only the code mapped into the Catch-up rows.

Q What's the "Incomplete Codes" banner I see on the Payroll Code Settings page? ›

It's a yellow warning banner telling you one or more active plans in the selected Payroll Group still needs codes mapped. It disappears once every plan has its required codes filled in. Click the How do I fix this? link on the banner to jump directly to the plans that need attention.

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk