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.
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.
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. |
OVERTIME_HOURLY | Yes | Hourly wages classified at the "overtime" rate. |
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.