Overview:

In Paylocity’s HR & Payroll module, employees can have recurring Earnings and Deductions for items like retirement (401(k), Roth, Loans) and benefits (medical, dental, vision). This guide explains core system concepts around processing codes, key field definitions (Effective Date, Begin Check Date, End Date, detCode, detType, etc), best practices and recommended scenarios so that a thoughtful integration can be designed.

The endpoints discussed through this document are commonly used for recurring processing scenarios, where the amount or rate does not change frequently. For use cases where the amount commonly changes from pay-period to pay-period, consider using the Pay Entry API in addition to aspects of the Pay Setup API.

Understanding Earnings & Deductions:

Within Paylocity’s HR & Payroll system, processing codes are categorized as either D – Deductions, E – Earnings, or T – Taxes – which inform the system’s processing rules, tax treatment, and reporting implications. These processing codes are sometimes referred to as a ‘detCode’ and they are paired with a ‘detType’ Earning Type or Deduction Type upon setup at the company level.

Earnings: Earnings are a specific type of payment or compensation within payroll, identifying how pay is categorized and treated for processing. Earnings codes track and record different types of pay, such as regular wages, overtime, bonuses, vacation, tips, and other compensation. In addition, memo-type earnings codes can be used to report informational amounts (e.g., employer-paid benefit contributions) without directly affecting net pay.
Deductions: A deduction is a specific type of withholding taken from an employee’s pay. These codes categorize and identify amounts withheld for items such as taxes, employee portions of insurance premiums, retirement contributions, garnishments, and other withholdings.

The taxability of any earning or deduction code is determined by its assigned detType, which then determines how payroll treats the amount (pretax or after-tax) and how tax forms (e.g., employee W-2 boxes) are generated.

What are Earning & Deduction Codes:

The earnings or deductions code value is determined at the company set-up level within the HR & Payroll Module. The code is the unique identifier for payroll processing. Each company ID is allowed to create their own custom definitions of earning and deduction codes. A call can be made to the GET endpoints of the Company Level Information API for current information on both Earning Codes and Deduction Codes. Access to processing codes setup within the employee record level would be found by calling the Pay Setup API.

Finding codes in the Paylocity UI

End users can identify and update current processing codes that are set up within the company by navigating to:

HR & Payroll > Configuration > Company Setup > Payroll > Earnings
HR & Payroll > Configuration > Company Setup > Payroll > Deductions

To identify processing codes that are set up within the employee record level, they would navigate to:

HR & Payroll > Employees > Employee Search > [Click Employee Name] > Pay > Pay Setup

Earning Types:

Earning Type	Definition
Banquet Tips	Tips an employee receives as part of a tip pool.
Cash Tips	Tips the employee receives in cash. Added in as an earning to calculate tax but backed out as a deduction as the employee has already received the funds.
Charged Tips	Tips the employee receives via an electronic payment method.
Group Term Life - Calculated	HR & Payroll automatically calculates employer-provided Group Term Life (GTL) (and its taxation) throughout the year at the pay frequency of the employee. Calculations based on the total insurance coverage amount for the employee.
Group Term Life - Flat Amount	This is a flat amount of GTL entered into HR & Payroll for an employee to be applied once a year.
HSA Employer Contribution	Earning type for an employer's contributions to a Health Savings Account.
Memo: Employer Match	Automatically used for Retirement Plan Employer Match earning codes such as “401ER”. Typically, part of an automated calculation based on Plan Compensation and Deferrals.
Memo: ERPS	Designed to record information for Enterprise Resource Planning Systems.
Memo: Generic Non-Calc Field	Most common Memo-Type, used for vast majority of memo coding.
Memo: Gross Receipts	Used to track Gross Receipts, typically for restaurants.
Memo Third Party Sick: Non-Taxable	Designed to record information for non-taxable Third-Party Sick Pay.
Memo: Tip Allocation	Designed to record the allocation of tips.
Memo: Washington Workers Compensation Calculation	Automatically used when the ERWSH code is used, and WALI taxes are configured.
Memo: Work Comp	Designed to be used with certain non-WALI Workers Compensation code setups.
Overtime	Unless exempt, employees covered by the Fair Labor Standards Act (FLSA) must receive overtime pay for hours worked over 40 in a workweek at a rate not less than 1.5 times the regular rate of pay.
Personal Use of Company Car	Referred to as Personal Use of Company Car (PUCC). The portion logged under the PUCC earning type is the portion included in the employee's wages to be taxed.
Qualified Moving Expenses	Moving expenses excluded from an employee's income as a fringe benefit.
Qualified Parking Reimbursement	Reimbursement to employees for qualified parking the employee pays for directly.
Regular Earning	Regular earnings within a working period. Taxable.
SCORP	Earnings paid by S Corporations (corporations owned by shareholders) to 2% shareholders for health and accident insurance premiums. These earnings are exempt from the Federal Insurance Contributions Act (FICA) and Federal Unemployment Tax Act (FUTA).
Section 132 Transit	Fringe benefits excluded from gross income per Internal Revenue Code Section 132(a).
Service Tips	The portion of a service fee paid to the employee. This is non-tip income as service charges are not tips. Service Charges include: - Large dining party automatic gratuity - Banquet event fee - Hotel room service charge - Bottle service charge.
Standard	Any earnings other than Regular (not normal work hours or over time) with the same taxability as Regular hours.
Third Party Sick: Long Term	Earning type for Long Term Disability (LTD) pay. LTD payments are exempt from Social Security, Medicare, Federal Unemployment Tax (FUTA), or State Unemployment Insurance (SUI) taxes.
Third Party Sick: Taxable	Earning type for Short Term Disability pay (STD)
Weighted OT	Weighted Overtime (OT) calculates overtime pay for a nonexempt employee who fits one of two conditions: - Works two or more different hourly rates - Has additional pay to include in the calculation

Deduction Types:

Deduction Type	Definition
401K	Use when the deduction represents pre-tax contributions to a 401(k)-retirement plan.
401K Loan	Use when an individual borrows money from 401(k) retirement fund. Post-tax deduction added as recurring deduction or added as one-time deduction in payroll. Some retirement vendors allow more than one loan per individual.
401k Over	Use if the deduction represents any contributions to a 401(k)-retirement plan more than the normal contribution limits.
401k Roth	Use if the deduction represents post-tax contributions to a 401(k) Roth retirement plan.
401k-non-S125	Use when 401(k) is not included in companies S125. It treats 401(k) deduction as taxable for those tax codes.
403b TSA (Tax Sheltered Annuity)	Use if the deduction represents pre-tax contributions to a 403(b) Tax Sheltered Annuity plan.
403b Roth	Use if the deduction represents post-tax contributions to a 403(b) Tax Sheltered Annuity plan.
403b Roth Catchup	Use if the deduction represents contributions to a 403(b) Tax Sheltered Annuity plan taken after taxes that exceed the normal limits for contributions. (Some plans may not allow catchup contributions.)
409A Nonqualified Deferred Compensation	Use if the deduction represents contributions to a nonqualified plan that does not fall under any other supported designation; including supplemental executive retirement plans (SERPs), voluntary deferral plans, equity arrangements, or any other arrangement that defers compensation to a later date.
457b Govt Plan	Use if the deduction represents contributions to a non-qualified plan intended for state and local government employees.
457b Roth	Use if the deduction represents contributions to a non-qualified plan intended for state and local government employees.
501c Non-profit Plan	Use if the deduction represents contributions to a non-qualified plan intended for employees of a non-profit organization who are not eligible to contribute to a 403(b) plan.
Add to Net	Mostly used for expenses or travel reimbursements. These deductions add to an employee’s Net on a given paycheck within a payroll batch.
Bankruptcy	Use when an employee declares bankruptcy and the employee is ordered to pay an amount per pay period toward a debt.
Cafeteria Plan	A cafeteria plan is a separate written plan that meets the specific requirements and regulations of section 125 of the Internal Revenue Code. Employers maintain the plan for employees. It provides participants with an opportunity to receive certain benefits on a pretax basis.
Creditor Garnishment	Use when an employee's wages are garnished by an individual or company to whom the employee owes money, determined by court order.
Dependent Care (Dependent Care Flexible Spending Account)	Allow employees to use pre-tax dollars to pay for eligible dependent care expenses incurred for the care of one or more qualifying individuals.
EFT Child Support	Use when child support order allows electronic submission of funds. Must have Case/Remittance ID and in most states, a Federal Information Processing Standardization (FIPS) code (or other appropriate state-specific code) stated on the child support order.
Federally Administrated Garnishment	Use when some portion of a person's earnings must be withheld for the payment of unpaid taxes or non-tax debts owed to the federal government. Issued by Internal Revenue Service (IRS), federal government, or state tax collection agencies.
Garnishment Fee	This deduction collects a fee from an employee who has a creditor garnishment or a child support order that the employer must enforce.
HSA 1099 Tax Exempt Contribution	For independent contractor contributions to a Health Savings Account. Employers do not withhold taxes for independent contractors.
HSA EE 125 Pretax Contribution	Use when HSA contributions are taken on a pre-tax basis.
HSA EE Post Tax Contribution	Use when HSA contributions are taken on a post-tax basis. Post tax contributions to HSA are tax-deductible as an above-the-line deduction, reducing taxable income by the amount of the contribution.
IMRF	Illinois Municipal Retirement Fund (IMRF) offers retirement plan services for employees of local governments and school districts within Illinois. Member and employer contributions are a legal requirement for governmental units participating in IMRF.
IRS Levy	Use to deduct wages from the employee's paycheck to be paid towards the fulfillment of a federal tax debt in amounts specified by the IRS. This form of levy deducts only from wages more than an exempt amount specified by the garnishment order.
Local Levy	Use to deduct wages from the employee's paycheck to be paid towards the fulfillment of a local tax debt in amounts specified by the collecting agency.
Memo	Information-only codes designed to record deductions while not affecting net wages or pay.
Non-EFT Child Support	Use when child support order does not allow/require electronic submission of funds or does not provide information sufficient to populate fields required for electronic submission.
Roth Catchup	Use if the deduction represents contributions to a Roth 401(k) plan taken after taxes that exceed the normal limits for contributions.
SEP IRA (Simplified Employee Pension Individual Retirement Account)	An IRA for sole proprietorships distinguished by requirements covering employee participation, nondiscrimination, withdrawals, and a formula for employer contributions. The owner can elect a certain percentage of the adjusted gross but must then give the same percentage to the employees as an employer contribution. Employees do not contribute. Although SEP must meet the general defined contributions plan standards, there are much less burdensome reporting requirements.
Simple IRA (Savings Incentive Match Plan for Employees Individual Retirement Account)	Used for tax-deferred employer-provided retirement plan funded by a pretax salary reduction.
Standard	Used for any deduction that has no special taxability.
State Levy	Used to deduct wages from the employee's paycheck to be paid towards the fulfillment of a state tax debt in amounts specified by the collecting agency.
Student Loan	Use to deduct wages from the employee’s paycheck to be paid towards the fulfillment of defaulted student loan debt in amounts specified by the collecting agency.
Tax Override	Can either block or exempt tax codes when setting up a Tax Override and set the W-2 box, if applicable. There are additional options for Tax Override deductions for when a specific priority is necessary. These options classify the deduction in the respective category and prioritize it among all the deductions accordingly.
Tax Override Benefit	Can either block or exempt tax codes when setting up a Tax Override and set the W-2 box, if applicable. There are additional options for Tax Override deductions for when a specific priority is necessary. These options classify the deduction in the respective category and prioritize it among all the deductions accordingly.
Tax Override Garnishment	Can either block or exempt tax codes when setting up a Tax Override and set the W-2 box, if applicable. There are additional options for Tax Override deductions for when a specific priority is necessary. These options classify the deduction in the respective category and prioritize it among all the deductions accordingly.
Tax Override Statutory	Can either block or exempt tax codes when setting up a Tax Override and set the W-2 box, if applicable. There are additional options for Tax Override deductions for when a specific priority is necessary. These options classify the deduction in the respective category and prioritize it among all the deductions accordingly.
WA Work Comp Rate	Use for Washington Labor and Industries (WALI) deductions when employer deducts an employee portion for WALI, and/or if employees have year-to-dates for WALI.
Work Comp	Contributions to a form of insurance where employees who are either injured or disabled on the job receive wage replacement.

Understanding the Data-Elements Involved:

Additionally, the following data-fields related to an earning or deduction code are critical to the success of payroll processing with earnings and/or deductions codes.

Effective Date represents the date the change officially goes into effect for reporting purposes. This is different from the Start Date or Begin Check Date.
Start Date / Begin Check Date is the first Check Date on which an employee's pay shows the new change. This date controls whether a record is considered historical, current, or future. This is different from the Effective Date.
- The Check Dates available for selection are the available present and future Check Dates entered in the Payroll Calendar.
End Date represents the last check-date that the processing will take place.
- The Check Dates available for selection are the available present and future Check Dates entered in the Payroll Calendar.
Amount vs. Rate:
Amount: the flat amount taken per paycheck by the deduction code or provided per paycheck by the earning code.
Rate: utilized on a ‘per-unit’ basis, such as hourly – for either earnings or deductions
Calculation Code: regarding deductions, the calculation code determines the type of math that is utilized in payroll processing to determine the amount on a given employee’s paycheck.
- Flat Amount: No calculation performs. The system uses the flat dollar amount entered in the Rate/Amount field.
- Garnishment: The system calculates and deducts 15% of the employees’ gross pay if the employee's disposable earnings are at least 45 times the Federal minimum wage.
- Configurable Garnishment: The system uses a standard calculation formula based on the selected state to configure the amount of the garnishment.
- Percentage of Gross: The system uses a percentage of gross pay.
- Percentage of Net: The system takes a percentage of disposable earnings (Gross - Taxes - [Codes within Net Code Group]).
Frequency: Pay frequency, also known as payroll frequency, refers to how often an employer pays their employees. It correlates to the number of pay periods in a year.

Daily (D)	Weekly (W)
Bi-Weekly (B)	Semi-Monthly (S)
Monthly take 1st week (MF)	Monthly take last week (ML)
Quarterly take 1st week (Q1W)	Quarterly take on last week (QLW)
Block Week 5 (BL5)	One Time (O)*

*Special Note: The One-Time (O) frequency permanently marks the earning or deduction as a single-use event; it is uncommon to utilize this frequency.

Goal & PaidToDate & PaidYearToDate:
- Goal: The Goal field defines the lifetime limit of the deduction and only accepts positive values. When the processing totals reach this limit, the employee’s pay no longer receives the deduction.
- PaidToDate: The Paid to Date field keeps a running tally of the amount paid towards the amount in the Goal field. Whenever the system applies the deduction to a worker’s check, the system automatically increases the amount in this field until said amount meets the amount in the Goal field. 
- PaidYearToDate: The Paid Year to Date field does not interact with the Paid to Date or Goal fields. Users entering a goal later than intended or after a deduction occurs must manually calculate and enter the Paid to Date amount with the Goal.
PayPeriod Minimum & Maximum:
- Use the Pay Period Minimum field to indicate the minimum amount of the earning on a single paycheck. If the calculated amount of the earning is less than the amount entered in this field, the Pay Period Minimum amount replaces the calculated amount.
- Use the Pay Period Maximum field to indicate the maximum amount of the earning on a single paycheck. If the calculated amount of the earning exceeds the amount entered in this field, the earning stops at the amount in the Pay Period Maximum field.
Annual Maximum: Overrides the system maximum, should one exist, such as for Retirement and Benefits.
Record Type: By using the recordType field, users can accurately categorize their records based on their temporal status, making it easier to sort, manage, and analyze data effectively.
- Historical: If the recordType is 'Historical', it indicates the record relates to past events and has either been archived or superseded by a 'Current' record, as defined by the Begin Check Date.
- Current: A 'Current' recordType indicates that the record is active and relevant to the present time. These records are currently in use and contain up-to-date information.
- Future Dated: The 'Future dated' recordType is for records that are scheduled for a future date. They represent planned or expected data or events.

Concepts to Consider

Activity	Recommendation
Eligibility & Status Changes	Your integration should evaluate employee eligibility for benefits or retirement plans. Using the data-elements available from the GET EMPLOYEE endpoints you can capture demographic details needed to calculate eligibility in your system. You will also need to consider what happens when changes occur in these fields throughout the lifecycle of an employee. Examples: Employment Status, Employment Type, Pay Type, Cost-Centers, Job Titles, Benefit Classes, Marital Status, Age/Gender.
Handling Dynamic Processing Codes	Your application should not force a specific processing code format or layout. Use GET /earnings and GET /deductions to identify each company’s active processing codes so you can handle them dynamically. Validate that your application correctly maps those codes to plan sources, honoring the detType and Taxability fields. Example: “401K” and “401CU” are both pre-tax sources in CompanyID 12345; whereas CompanyID 67890 uses “401R” as their processing code.
Payroll Calendar Alignment	Run a Check Date Listing report from HR & Payroll to understand each company’s payroll calendar schema.
Duplicate Records & Company Transfers	Simulate employee transfer between Company IDs within a Company Set. Confirm that active enrollments end-date on the originating company and re-establish correctly on the new company. Using de-duplication and collision logic, ensure duplicate records are handled appropriately where benefits are terminated inadvertently.
Submitting Final “Ready to Process” Data	Submit deferrals for earnings and deductions after Benefit Enrollments are closed. Paylocity should only receive “Ready to Process” data, as opposed to Enrollment Window data – which can change day to day.
Transitional Enrollments	Create a scenario where a new hire or newly eligible employee’s benefits begin before the next plan year. Verify initial enrollment processes successfully and that a separate Open Enrollment event later updates the record for the new plan year.
Passive Enrollment Handling	In a passive enrollment test, keep existing earnings/deductions active and submit changes only for employees who updated their elections. Confirm unchanged records remain intact.
Active Enrollment Handling	In an active enrollment test, end-date all current records at the end of the plan year, then submit new records only for employees who completed enrollment. Confirm all records reset cleanly.

Test Scenarios

Scenario	Test Requirement
Open Enrollment Period: Opt-Out, Declined Coverage	In the event of an opt-out or declined coverage, no data should be sent via API to Paylocity (As a best-practice, Paylocity only accepts “Ready to Process Payroll” data). If prior-year coverage exists, ensure benefits are properly end-dated if not already. Send a successful PUT Earnings and/or Deductions request to Opt-Out of existing coverage from a prior plan-year. Test end-dating behavior using a PUT call with an End Date instead of passing $0.00 values. Confirm records stop processing and remain reportable without data duplication.
Open Enrollment Period: Electing New Benefit(s) Life Events: Adding New Benefit(s)	Add new coverage during open enrollment or life events. Send a successful POST Earnings and/or Deductions request that represents the new benefits.
Open Enrollment Period: Updating Existing Benefit(s) Life Events: Updating Existing Benefit(s)	Modify existing coverage. Send a successful PUT Earnings and/or Deductions request such as to update the deferral amount/rate for a given benefit.
Terminating Benefit (End Date of Coverage) Life Events: Terminating Existing Benefit(s)	Terminate existing coverage. Send a successful PUT Earnings and/or Deductions request. Note: Perform a GET Earnings and/or Deductions request first to retrieve the Resource ID required in the PUT request URI.
End-Date Sequencing	Ensure proper sequence when moving between plans (e.g., MED PLAN 1 → MED PLAN 2). End-date the old plan’s processing codes before sending data for the new plan using a PUT Earnings and/or Deductions request.
Handling Retirement Loans	Validate loan processing codes. Use the loan401K object in GET DEDUCTIONS to match loan numbers with processing codes (e.g., 401L1). When a loan is satisfied, iterate to the next available code (401L1 → 401L2) instead of recycling old codes. This ensures a cleaner & clearer register report after payroll processing has taken place.
Handling GTL (Calculated vs. Flat)	Handle imputed income correctly for GTL If the Benefits System is calculating the amount, utilize “GTL1” and pass the following: - effectiveFrom date - effectiveTo date - code (GTL1) - rate If the Payroll System is calculating the amount, utilize “GTL” and pass the following: - effectiveFrom date - effectiveTo Date - code (GTL) - units (This should be the full amount of the Group Term Life Policy, not just the amount over $50,000)