United States

The U.S. payroll localization covers salary computations for employees, including both employee and employer payroll taxes. It accounts for federal and state regulations.

The states included in this localization are:

• California (CA)

• New York (NY)

• Texas (TX)

• Florida (FL)

• Colorado (CO)

• Alabama (AL)

• Washington (WA)

• Nevada (NV)

Note

Federal taxes (Income, FICA, and Unemployment) for both employees and employers are covered by default in the Odoo U.S. Payroll localization. Additional states will be added over time, so check back for updates.

Before configuring the United States localization, refer to the general payroll documentation, which includes the basic information for all localizations, as well as all universal settings and fields.

Apps & modules

Install the following modules to get all the features of the United States payroll localization:

Name	Technical name	Dependencies	Description
United States - Payroll	l10n_us_hr_payroll	hr_payroll hr_contract_reports hr_work_entry_holidays hr_payroll_holidays	Provides U.S. payroll basics, including employee tax details, salary structures (Basic/Gross/Net), tax rules, and W-2/3PA reporting.
United States - Payroll with Accounting	l10n_us_hr_payroll_account	hr_payroll_account l10n_us l10n_us_hr_payroll	Links payroll and accounting by creating journal entries (per payslip if needed) to record payroll in the company’s books.

See also

Configure the United States fiscal localization

General configurations

First, the company must be configured. Navigate to Settings app ‣ Users & Companies ‣ Companies. From the list, select the desired company, and configure the following fields:

• Company Name: Enter the business name in this field.

• Address: Complete the full address, including the City, State, Zip Code, and Country.

  Important

  The state selected in the company’s address is associated as the work address by default for the employee, and the one used to calculate payroll taxes.

• Tax ID: Enter the company’s EIN.

• Company ID : Enter the business’s state ID number.

• Currency: By default, USD is selected. If not, select USD from the drop-down menu.

• Phone: Enter the company phone number.

• Email: Enter the email used for general contact information.

Warning

Ensure the information is accurate, as it is used when creating W-2s.

Employees

Every employee being paid must have their employee profiles configured for the United States payroll localization. Additional fields are present after configuring the database for the United States.

To update an employee form, open the Employees app and click on the desired employee record. On the employee form, configure the required fields in the related tabs.

Work tab

Enter the Work Address for the employee in the Location section of the Work tab.

Important

The state selected in this address determines which salary rules Odoo applies when calculating taxes.

Personal tab

Ensure the employee has a minimum of one trusted bank account listed in the Bank Accounts field in the Private Contact section.

These accounts are used to pay the employee, via an automation through a NACHA payment file. Payroll cannot be processed for employees without a trusted bank account. If no trusted bank account is set, a warning appears on the Payroll dashboard and an error occurs when attempting to run payroll.

Ensure there is a valid SSN No entered in the Citizenship section . The last four digits of the SSN number appears on the employee’s payslips.

Payroll tab

Contract overview section

This section holds information that drives salary calculations. Ensure the following fields are configured:

• Contract: The Validity of the compensation conditions can be updated depending on the needs.

• Wage Type: Select how the employee is paid.

  • Select Fixed Wage for salaried employees who receive the same amount each pay period.

  • Select Hourly Wage for employees paid based on hours worked.

  Tip

  Set a default Wage Type in the salary Structure Type to configure employees in bulk. If needed, the default can be overridden on individual employee records if exceptions are needed.

• Contract Type: Determines how the employee is paid and classified, such as Salary-exempt, Salary-nonexempt, Hourly.

  Important

  This field is visible on payslips. Some states require payslips to state if the employee is exempt or non-exempt from overtime. Ensure the selection follows the state laws.

• Pay Category: Select United States: Employee for this field. This defines when the employee is paid, their default working schedule, and the work entry type it applies to.

Schedule section

• Work Entry Source: Defines how work entries are generated for payroll during the specified pay period. The options are:

  • Working Schedule: Based on the employee’s assigned working schedule (e.g., 40 hours per week).

  • Attendances: Based on approved checked-in hours in the Attendances app.

  • Planning: Based on scheduled shifts in the Planning app.

• Extra Hours: Tick the checkbox to allow the Attendances app to add any extra work entries logged by the employee.

• Working Hours: Using the drop-down menu, select the default work schedule. This is particularly important for employees available to receive overtime pay (typically hourly employees, not salaried).

W-2 form section

A W-2 is an annual tax form that reports an employee’s wages, taxes, and benefits. Employees use it to file their tax returns. The options below correspond to checkboxes in box 13 of the W-2 form. Select any that apply to the employee.

• Statutory Employee: Tick this box if the employee is exempt from income tax, but subject to FICA taxes.

• Retirement Plan: Tick this box if the employee is an active contributor to an employer-sponsored retirement plan.

• Third-Party Sick Pay: Tick this box if the employee is covered under a plan where sick pay benefits may be provided by a third party (e.g., an insurance company) during the year.

W-4 form section

A W-4 is an IRS form that determines an employee’s federal tax withholding, which the employer remits directly to the IRS.

Configure any relevant fields for the employee in this section.

State filing section

An employee’s marital status impacts their payroll taxes. Configure the following fields regarding their status and withholdings.

• Status: Using the drop-down menu, select the employee’s federal filing status. The options are Single, Married/RDP filing jointly, Married/RDP filing separately, Head of household, or Qualifying surviving spouse/RDP with child. This typically comes from the employee’s W-4 form.

• Tax Status: Using the drop-down menu, select the employee’s state filing status, if applicable.

  Tip

  The federal and state statuses do not need to match.

  Note

  As of 2025, these states do not collect state income tax: Alaska, Florida, Nevada, New Hampshire, South Dakota, Tennessee, Texas, Washington, and Wyoming. If a payroll localization exists for these states, there are no corresponding state options in the Tax Status field. Leave it blank.

• Withholding Allowance: Enter the total annual amount to be withheld from the employee’s pay for the year, for state taxes. Only fill this out if the employee lives in a state with state income tax.

• Extra Withholding: Enter the total extra annual amount (not including the Withholding Allowance amount) to be withheld from the employee’s pay for the year, for state taxes, if the employee lives in a state with state income tax.

Common benefits

The following sections of benefits are considered common ones offered by US employers. This information needs to be populated with the information selected by the employee.

Note

The benefits listed in this section are considered the most commonly offered by companies. If other employee benefits exist that require regular paycheck deductions, they can be added as inputs.

Pre-tax deductions

Pre-tax benefits lower the employee’s gross wage, which decreases the base amount for tax calculations. These are displayed at the beginning of the payslip before the gross wage is stipulated.

Retirement plans section

This section is where the employee and employer 401(k) contributions are configured. Fill out the following fields:

• 401(k): Enter the amount of money taken out of the employee’s payslip each pay period. This can be entered either as a percentage (%) of the payslip amount, or a specific dollar amount per payslip ($/slip).

• Matching Amount: Enter the matching amount the employer contributes to the employee’s 401(k), as compared to the employee’s contributions. This field can also be configured as either a percentage (%) of the employee’s contribution, or a specific dollar amount ($/slip).

• Matching Yearly Cap: If there is a limit to the employer’s contribution, enter it as a percentage of the employee’s annual salary.

Example

A company allows employees to contribute to a 401(k) retirement plan, and matches 50% of the employee’s contributions, up to $5,000 USD a year. The employee earns $50,000 USD a year, and contributes 20% of their pay to their 401(k), which is $10,000 USD.

To configure this, enter 20.00 in the 401(k) field, 50.00 in the Matching Amount field, and 20.00 in the Matching Yearly Cap field.

Health benefits section

This section is where the employee’s health contributions are configured. Populate each of the fields with the corresponding amount deducted from each paycheck for the employee.

Other benefits section

This section currently only houses a Commuter benefit field. Enter the amount being deducted per paycheck, for applicable commuter benefits.

Post-tax deductions section

These types of benefits count as deductions after taxes are calculated. They appear towards the end of the payslip before the net amount is displayed. Currently, only one field, ROTH 401(k) appears in this section. Enter either a percentage (%) of the payslip amount, or a specific dollar amount per payslip ($/slip) being deducted from the employee’s pay, and deposited into a ROTH 401(k) account.

Payroll configuration

Several sections within the Payroll app installs a Salary Structure, Structure Type, Rules, and Parameters specific to the United States.

Salary structures & structure types

When the l10n_us_hr_payroll module is installed, a new Salary Structure gets installed, United States: Regular Pay. This structure includes one Structure Type, United States: Regular Pay.

The Salary Structure contains all the individual salary rules that informs the Payroll app how to calculate employee payslips.

Salary rules

To view the salary rules that inform the salary structure what to do, navigate to Payroll app ‣ Configuration ‣ Structures and expand the United States: Employee group to reveal the United States: Regular Pay structure type. Click United States: Regular Pay to view the detailed salary rules.

Each rule defines how pay is calculated, taking into account factors such as commissions, bonuses, taxes, and insurance. The logic behind the United States: Regular Pay rules is as follows:

• The first four rules listed reflects all sources of income, including the basic wage listed on the contract (Basic Salary), plus any allowances, such as Commissions, Tips, and Bonuses.

  

• Adding up these inputs is how the gross salary (Gross Pay) is calculated. This amount is the base amount used to calculate payroll taxes.

• The next set of rules are the various pre-tax benefits and taxable income, such as Medical insurance contributions and Commuter Benefits. After the employee’s Gross Pay is calculated, Odoo deducts all the pre-tax benefits listed on the employee’s contract to determine the employee’s Taxable Income.

  

• Next, all the various tax rules are listed where both federal and state payroll withholdings are outlined. First, federal tax rules are listed, then any state rules (if any) are listed.

  

  Note

  The rule for federal withholdings for Worker's Compensation appears after several state-specific withholdings are listed, and does not appear in the above image, but are listed in the rules.

• The last rules listed are the post-tax employee deductions.

  

• The Other Inputs tab contains anything else affecting payroll. This includes items to be added to the payslip, such as Tips, and other deductions, such as Child Support.

  

• The employee’s net salary is the amount the employee receives from the employer. The formula to calculate the net salary is:

  \[\text{Gross Salary} + \text{Allowances} - \text{Payroll Taxes} - \text{General Deductions}\]

• Additionally, an extra section exists in payroll calculation for the US called Employer Deductions, and it breaks down the payments the employer must make as their portion of payroll taxes.

  

  Note

  The rule for employer deductions for Worker's Compensation appears after several state-specific employer deductions are listed, and does not appear in the above image, but are listed in the rules.

Rule parameters

Some calculations require specific rates associated with them, or wage caps. Rules Parameters are capable of listing a value, either a percentage or a fixed amount, to reference in the salary rules.

Example

The wage base for Social Security tax calculations has a cap for 2025, accounted for in the US: FICA OASDI Cap parameter.

Most rules pull information stored in the parameters module to get the rate of the rule (a percentage) and the cap (a dollar amount).

To view rule parameters, navigate to Payroll app ‣ Configuration ‣ Rule Parameters. Here, all rule parameters are displayed with their linked Salary Rules, which can be accessed. Review the parameters associated with a rule by looking for the Name of the rule, and make any edits as needed.

Example

The Unemployment tax of a company is different from the one added by default in Odoo. To update this, navigate to Payroll app ‣ Configuration ‣ Rule Parameters, then, filter the results by FUTA, or the name of the state that needs editing, and edit the corresponding rate from the list.

Important

Odoo adds updated rule parameters for the current calendar year. It is not recommended to edit rule parameters unless a federal or state parameter has changed, and is different from the rule parameters created by Odoo. Check with all local and national regulations before making any changes to rule parameters.

Run US payroll

Before running paypoll, the payroll officer must validate employee work entries to confirm pay accuracy and catch errors. This includes checking that all time off is approved and any overtime is appropriate.

Work entries sync based on the employee’s contract configuration. Odoo pulls from the assigned working schedule, attendance records, planning schedule, and approved time off.

Any discrepencies or conflicts must be resolved, then the work entries can be regenerated.

Once everything is correct, draft payslips can be created individually or in batches, referred to in the Payroll app as Pay Runs.

Note

To cut down on the payroll officer’s time, it is typical to process payslips in batches, either by wage type (fixed salary vs hourly), pay schedule (weekly, bi-weekly, monthly, etc.), department (direct cost vs. administration), or any other grouping that best suits the company.

The process of running payroll includes different actions that need to be executed to ensure that the amount withheld from payroll taxes is correct, the amount that the employee receives as their net salary is correct, and the computation of hours worked reflects the employee’s actual hours worked, among others.

When running a payroll batch, check that the period, company, and employees included are correct before starting to analyze or validate the data.

Once the payslips are drafted, review them for accuracy. Check the Worked Days & Inputs tab, and ensure the listed worked time is correct, as well as any other inputs. Add any missing inputs, such as commissions, tips, reimbursements, that are missing.

Next, check the various totals (gross pay, employee taxes, benefits, employer taxes, net salaries), then click Compute Sheet to update the salary calculations, if there were edits. If everything is correct, click Validate.

Accounting check

The accounting process when running payroll has two components: creating journal entries, and registering payments.

Journal entry creation

After payslips are confirmed and validated, journal entries are posted either individually, or in a batch. The journal entry is created first as a draft.

Important

It must be decided if journal entries are done individually or in batches before running payroll.

Four accounts from the US CoA are included with the payroll localization:

• 611000 Salaries & Wages: Records gross salary and the employer’s portion of payroll expenses. Also groups values from rules without specific accounts (e.g., company-specific benefits).

• 230100 Employee Payroll Taxes: Withheld taxes from employees, which the employer must file and pay. The partner and label columns of the journal entry indicate the specific tax.

• 230200 Employer Payroll Taxes: Employer portion of payroll taxes to be filed and paid. The partner and label columns of the journal entry indicate the specific tax.

• 230000 Salary Payable: Net salary owed to the employee.

Note

The CoA configuration is done by default when a company is located in the US. The account codes and names can be edited to suit the company’s needs. If there is no CoA account associated with a salary rule (used in a salary structure), Odoo uses the account Salary Expenses to create the journal entry, regardless of the nature of the move.

If everything seems correct on the journal entry draft, post the journal entries.

Register Payments

After the journal entries are validated, Odoo can generate payments.

Important

To generate payments from payslips,employee’s must have a trusted bank account. If the employee’s bank account is not marked as trusted, NACHA files cannot be generated through Odoo.

Payments can be Grouped by Partner if there is a partner associated with a salary rule.

Close Payroll

If there are no errors, payroll is completed for the pay period.

Reports

The US localization contains several reports unique to the US, which provide tax information for employees, as well as the ability to integrate with outside organizations such as ADP.

W2 Report

The W2 Report provides a CSV file that allows employees to e-file their W2 report with third-party software. To access this report, navigate to Payroll -> Reporting -> United States -> W2.

To create a W2 form, click New, and a blank Create W2 Form page loads. Set the Start Date and End Date (typically a calendar year), and select the Company, if in a multi-company database.

All pay runs for the time period appear in a list view. To add any missing pay runs, click Add a line at the bottom of the list, and select the missing files.

When done, click the Generate button to create a CSV file with a summary of all payroll related payments made during the specified time period.

Form 941

The Form 941 report is meant to inform the government of the amount of federal income tax, FICA taxes (Medicare and Social Security) withheld from employee paychecks. It also reports the employee’s side of taxes.

To create this report, navigate to Payroll -> Reporting -> United States -> Form 941. Click the New button, and a new Form 941 report page loads. Configure the information on the top portion of the form, including the Company, Tax Year, Quarter, IRS Payment Option (how the money is being sent to the IRS), and Deposit Schedule and Tax Liability (how often payments are made to the IRS).

All pay runs for the time period appear in a list view. To add any missing pay runs, click Add a line at the bottom of the list, and select the missing files.

When done, click Generate, and the report is created as a CSV file, and appears on the Form 941 report dashboard. Companies then download and submit this report through a third party for e-filing.

Form 940

The Form 940 report details the annual FUTA withheld for payroll.

To create this report, navigate to Payroll -> Reporting -> United States -> Form 940. Click the New button, and a new Form 940 report page loads. Configure the information on the top portion of the form, including the Company, Tax Year, Single State Payer, Multi State Employer, Paid in Credit Reduction State, and IRS Payment Option (how the money is being sent to the IRS).

All pay runs for the time period appear in a list view. To add any missing pay runs, click Add a line at the bottom of the list, and select the missing files.

When done, click Generate, and the report is created as a CSV file, and appears on the Form 940 report dashboard. Companies then download and submit this report through a third party for e-filing.

Export data to third-party apps

The ADP Export report generates a CSV file that can be submitted to ADP, which then makes payments to the employees.

The CSV file summarizes the employee’s worked hours during a specified time period, correlating to their salary or hourly wage. The report is generated from work entry after any time off is confirmed.

The export format is meant to match with the ADP format. Since companies can customize their portal and may require some changes, the data is there to be fed to ADP to run payroll in it.

Important

To access the ADP Export report, the United States - Payroll - Export to ADP module must be installed.