Pay codes are the "categories" that wages, reimbursements, and deductions are placed into. Every pay code has a human-readable name, shown on reports, pay stubs, and elsewhere; a string key, apiKey, used to reference it in API integrations and other workflows; and a type that controls how amounts using it are treated in payroll. The Pay Codes API lets you list a company's pay codes and create new ones.
| Endpoint | What it does |
|---|---|
| List pay codes | Lists the company's configured pay codes |
| Create a pay code | Creates a new pay code for the company |
How pay codes are used
Other APIs, such as the Payables API, reference a pay code by its apiKey. An apiKey is an alphanumeric string that LOOKS_LIKE_THIS: only uppercase letters, numbers, and underscores (_) are allowed.
Each company has its own list of pay codes, and also comes configured with a built-in list of default pay codes. Generally, use a separate pay code for each wage, reimbursement, and deduction type, so the numbers for each type are tracked and displayed separately.
For background on how amounts are typically calculated for common pay codes, like overtime, salary, and mileage, see Pay codes and gross pay basics.
Pay code types
When you create a pay code, its payCodeType controls how amounts using it are treated:
payCodeType | Use it for | How amounts are treated |
|---|---|---|
TAXABLE_PAY | Wages, or contractor pay | Subject to tax withholding under the tax rules of the worker being paid. For an employee that typically means income tax withholding and FICA, and the amount is included in Box 1 of Form W-2. For a contractor, no tax withholding is generally applied. |
NON_TAXABLE_PAY | Reimbursements and other non-wage items | Treated as non-wage amounts and never subject to tax withholding. Not included in Box 1 of Form W-2 for employees. |
DEDUCTION | One-time deductions | Treated as post-tax deductions: taken from the pay that remains after pre-tax deductions, tax withholding, and retirement contributions are removed. |
Despite the name, TAXABLE_PAY doesn't mean the amount is always taxed. Withholding depends on the worker being paid.
Creating a DEDUCTION pay code, and submitting amounts under it, doesn't create any recurring deduction rules. These pay codes are for one-time deduction amounts only. Recurring deductions for benefit plans like medical or vision, retirement contributions, and other deductions like dues or loan repayments can be managed with the Deductions API. Other recurring deductions, such as wage garnishment, are set up in the Everee admin portal.
Leave pay codes
Every leave type has its own pay code, with an apiKey that starts with TIME_OFF_TYPE_, like TIME_OFF_TYPE_VACATION. List pay codes returns them along with your other pay codes, so it's the one place to find every pay code you can use. They're created for you when you create a leave type with the Leave Accrual API, which also returns each leave type's payCode.
To pay out leave, send a payable item coded to a leave type's pay code. See Managing leave and PTO.
Naming pay codes
We strongly encourage readable names and keys. Some legacy payroll systems create pay codes in ambiguous lists, like every code from BONUS1 to BONUS10. Specify each pay code's name and apiKey clearly and unambiguously instead.
Default pay codes
The following default pay codes are supported in various APIs. They are always available to every company, with no setup required.
If your company needs pay codes beyond these defaults, you can create custom pay codes with Create a pay code. Custom pay codes are referenced by their API key, in the same places the default codes are used.
| Type | Taxable to Employees | Description |
|---|---|---|
REGULAR_HOURLY | Yes | Hourly wages classified at the "regular" (non-overtime) rate. |
FLSA_QUALIFIED_OVERTIME | Yes | Hourly overtime required by the FLSA: hours over 40 in a workweek. Its premium is qualified overtime compensation under the OBBBA. |
NON_FLSA_QUALIFIED_OVERTIME | Yes | All other hourly overtime, like daily overtime required only by state law. |
DOUBLE_TIME_HOURLY | Yes | Hourly wages classified at the "double time" rate. |
REGULAR_SALARY | Yes | Wages earned by a salaried employee. |
REIMBURSEMENT | No | Reimbursement for expenses. |
CONTRACTOR | No | Payout to a contractor for services. |
TIPS | Yes | Tips earned during an employee's hourly work period. |
PER_DIEM | Yes | Amount paid to an employee as a per diem. |
COMMISSION | Yes | Commissions earned. |
BONUS | Yes | Bonuses earned. |
HOLIDAY | Yes | Amount paid for hours occurring on a holiday. |
VACATION | Yes | Amount paid for vacation hours, typically accrued or granted via a PTO policy. |
SICK | Yes | Amount paid for sick hours, typically accrued or granted via a PTO or sick-time policy. |
ADVANCE | Yes | Amount advanced to an employee against future wages. This amount is not automatically deducted from future wages. |
SEPARATION | Yes | Flat amount paid to an employee as part of a separation or termination agreement. |
MILEAGE | Yes | Mileage reimbursement. |
EARNINGS_ON_DEMAND | Yes | Amount to be paid out "early" in a pay period. |
These default pay codes (also known as earning types) can be used for either employee earnings or contractor pay, as needed, except for the CONTRACTOR code, which should only be used for contractor pay.
OVERTIME_HOURLY is deprecated. Send overtime under FLSA_QUALIFIED_OVERTIME or NON_FLSA_QUALIFIED_OVERTIME instead, so qualified overtime is reported separately. OVERTIME_HOURLY can still appear on earnings you read, like payment data and payroll cost. See Complying with the OBBBA overtime rule.