[ADD] Payroll: Add United States Localization #14614

larm-odoo · 2025-09-19T18:04:24Z

Adding USA localization info. Used this document template to add all the information needed for this.

Original task card for this PR.

robodoo · 2025-09-19T18:04:27Z

larm-odoo · 2025-09-19T18:15:51Z

Hi @Felicious! I am tagging you first to see if the structure, order, etc of this doc seems good, or if there are any suggestions ot reogranize this to make it better. I am SO excited to get this doc published, so I can move onto the others!

larm-odoo · 2025-09-22T16:34:06Z

Hello @cas-odoo - here is the USA localization document. I believe I made everything clear from the doc you sent, but there may be parts that I read or misunderstood when I re-wrote sections. I have not added any images yet, since I want to be sure the INFO is correct, then I will add any important images (things that I think users will need to see for clarification). Please let me know if everything in here is accurate/correct/or there is anything that may be too vague or misunderstood by the reader. I appreciate your assistance with this!

content/applications/hr/payroll/payroll_localizations/united_states.rst

larm-odoo · 2025-09-25T19:47:37Z

Hello @cas-odoo - I have added images, and I was hoping you can let me know if they seem correct/in the right place? I am having a hard time figuring out what to show and where, so if you can take a look at the images, and let me know if any should move or be changed, I'd appreciate it!

cas-odoo · 2025-09-25T20:59:32Z

content/applications/hr/payroll/payroll_localizations/united_states/structure-types.png

I would skip this image, as it could be confusing to see the standard "employee" and "worker" structure

cas-odoo · 2025-09-25T21:00:43Z

content/applications/hr/payroll/payroll_localizations/united_states/us-rules-top-half.png

I would add this image in this section https://runbot225.odoo.com/runbot/static/build/89854217-19-0/logs/build/html/applications/hr/payroll/payroll_localizations/united_states.html#salary-structures-structure-types rather than rules and would keep rules without an image associated with it

cas-odoo · 2025-09-25T21:17:20Z

content/applications/hr/payroll/payroll_localizations/united_states.rst

+Register Payments
+-----------------
+
+After the :ref:`journla entries <payroll/journal>` are validated, Odoo can generate payments.


Correct to "journal" instead of "journla"

Felicious · 2025-09-26T00:58:39Z

content/applications/hr/payroll/payroll_localizations/united_states.rst

+The localization for payroll in the United States consists of the process of salary computation for
+employees, including Payroll tax calculations (employee and employer portions). It takes into
+consideration Federal and State regulations.
+
+The States included in this localization are:


I dont think we need to capitalize "The States" here (: Below is a suggestion to rewrite this intro for brevity. Optional!

Suggested change

The localization for payroll in the United States consists of the process of salary computation for

employees, including Payroll tax calculations (employee and employer portions). It takes into

consideration Federal and State regulations.

The States included in this localization are:

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:

Felicious · 2025-09-26T01:35:32Z

content/applications/hr/payroll/payroll_localizations/united_states.rst

+  Federal portion of taxes (Income, :abbr:`FICA (Federal Insurance Contributions Act)`, and
+  Unemployment) for employee and employer are covered by default with the current Odoo Payroll US
+  localization. Check back as more states are added.


(required change) this indent should be one space more to the right (:

(optional suggestion) reword for brevity for the first sentence, and made the "check back later" sentence more formal and ❇️ professional ❇️ :

Suggested change

Federal portion of taxes (Income, :abbr:`FICA (Federal Insurance Contributions Act)`, and

Unemployment) for employee and employer are covered by default with the current Odoo Payroll US

localization. Check back as more states are added.

Federal taxes (Income, :abbr:`FICA (Federal Insurance Contributions Act)`, 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.

Felicious · 2025-09-26T22:00:58Z

content/applications/hr/payroll/payroll_localizations/united_states.rst

+     - This module includes all the basics for United States Payroll. Installing this module
+       automatically installs: employee tax filing details; contract basis of pay and benefits; a
+       salary type for the US with a common structure with Basic/Gross/Net Salary calculation;
+       salary rules for correct employee and employer tax calculations, and W2 and 3PA reporting
+       capabilities.


was wondering why we separated the items in the installation list with a semicolon?

Also, this is more of a nitpick more than anything but the description is a little long. I wanted to play with either a shortened description or trying to format the list in bullet so it's easier to scan (: I'll attach different versions and RST snippets for you to choose the best one!

Concise version:

Suggested change

- This module includes all the basics for United States Payroll. Installing this module

automatically installs: employee tax filing details; contract basis of pay and benefits; a

salary type for the US with a common structure with Basic/Gross/Net Salary calculation;

salary rules for correct employee and employer tax calculations, and W2 and 3PA reporting

capabilities.

- Provides U.S. payroll basics, including employee tax details, salary structures

(Basic/Gross/Net), tax rules, and W-2/3PA reporting.

Bullet points version

Suggested change

- This module includes all the basics for United States Payroll. Installing this module

automatically installs: employee tax filing details; contract basis of pay and benefits; a

salary type for the US with a common structure with Basic/Gross/Net Salary calculation;

salary rules for correct employee and employer tax calculations, and W2 and 3PA reporting

capabilities.

- Installs all the basics for United States Payroll

- employee tax filing details

- contract basis of pay and benefits

- a salary type for the US with a common structure (Basic/Gross/Net Salary calculation)

- salary rules for correct employee and employer tax calculations

- W2 and 3PA reporting capabilities

Felicious · 2025-09-26T22:26:32Z

content/applications/hr/payroll/payroll_localizations/united_states.rst

+Companies --> Companies`. From the list, select the desired company, and configure the following
+fields:
+
+- :guilabel:`Name`: Enter the business name in this field.


Suggested change

- :guilabel:`Name`: Enter the business name in this field.

- :guilabel:`Company Name`: Enter the business name in this field.

Felicious · 2025-09-26T22:32:26Z

content/applications/hr/payroll/payroll_localizations/united_states.rst

+     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.
+
+- :guilabel:`Tax ID`: Enter the business's :abbr:`Employer identification number (EIN)`.


the abbreviation is switched around --> it's the abbreviation, THEN the fully written out phrase.

Also, I suggest we change "business" to "company" so we don't get that funky "business's"

Suggested change

- :guilabel:`Tax ID`: Enter the business's :abbr:`Employer identification number (EIN)`.

- :guilabel:`Tax ID`: Enter the company's :abbr:`EIN (Employer Identification Number)`.

Felicious · 2025-09-28T22:58:02Z

content/applications/hr/payroll/payroll_localizations/united_states.rst

+payroll.
+
+To create this report, navigate to :menuselection:`Payroll -> Reporting -> United States -> Form
+940`. CLick the :guilabel:`New` button, and a new :guilabel:`Form 940` report page loads. Configure


Suggested change

940`. CLick the :guilabel:`New` button, and a new :guilabel:`Form 940` report page loads. Configure

940`. Click the :guilabel:`New` button, and a new :guilabel:`Form 940` report page loads. Configure

Felicious · 2025-09-28T22:58:24Z

content/applications/hr/payroll/payroll_localizations/united_states.rst

+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 worked hours during a specified time period, correlating to


Suggested change

The CSV file summarizes the employee worked hours during a specified time period, correlating to

The CSV file summarizes the employee's worked hours during a specified time period, correlating to

Felicious · 2025-09-28T22:58:38Z

content/applications/hr/payroll/payroll_localizations/united_states.rst

+
+.. important::
+   To access the ADP Export report, the `United States - Payroll - Export to ADP` module **must** be
+   :ref:`Iinstalled <general/install>`.


Suggested change

:ref:`Iinstalled <general/install>`.

:ref:`installed <general/install>`.

Felicious · 2025-09-28T23:09:04Z

content/applications/hr/payroll/payroll_localizations/united_states.rst

+     - hr_payroll
+       hr_contract_reports
+       hr_work_entry_holidays
+       hr_payroll_holidays


Even though these are on new lines, they're not formatting properly and do not display on new lines:

To fix this, I added bullet points

Suggested change

- hr_payroll

hr_contract_reports

hr_work_entry_holidays

hr_payroll_holidays

- - hr_payroll

- hr_contract_reports

- hr_work_entry_holidays

- hr_payroll_holidays

This is what it looks like now!

Felicious · 2025-09-28T23:10:19Z

content/applications/hr/payroll/payroll_localizations/united_states.rst

+   :doc:`United States fiscal localization documentation
+   <../../../finance/fiscal_localizations/united_states>`


why might the reader want to go to this page?

Suggested change

:doc:`United States fiscal localization documentation

<../../../finance/fiscal_localizations/united_states>`

:doc:`Configure the United States fiscal localization

<../../../finance/fiscal_localizations/united_states>`

Felicious · 2025-09-28T23:31:37Z

Appreciate the heavy lift on this long, detailed doc, @larm-odoo and @cas-odoo! 👏

Since @larm-odoo is OOO, I applied light, review-scoped edits directly in this PR to keep it moving. I’ve left ~50 inline comments, each tied to a diff so Lara can audit every change and revert/adjust as needed. A lot of my suggestions aim to clarify U.S.-specific payroll behavior; I’m not a payroll SME, so I’m leaning on your expertise to validate the details.

What I changed (brief summary):

Tightened grammar/capitalization and standardized form names (e.g. W-2).
Small improvements for brevity throughout the doc.
When applicable, moved background/context info into admonition blocks so the main flow stays scannable
Highlighted areas where US-specific logic could be emphasized even more
Shortened table cells and removed duplication with linked references.

What I still need from you, @larm-odoo!

Please sanity-check the lines I changed and call out anything inaccurate or oversimplified.
If I misinterpreted something, feel free to propose exact wording in the follow-up PR.
In a follow-up PR, let's condense a workflow section into a how-to guide format using numbered lists (we can talk offline about this!

Spot-check focus areas

Payroll modules: link
Wages: link
Work entries generation: link
W-2: link
Benefits: link
Contract validity: link

Felicious · 2025-09-29T02:19:41Z

@robodoo r+

C3POdoo requested review from a team September 19, 2025 18:06

larm-odoo self-assigned this Sep 19, 2025

larm-odoo added the 5 label Sep 19, 2025

larm-odoo requested a review from Felicious September 19, 2025 18:12

larm-odoo requested a review from cas-odoo September 22, 2025 16:31

cas-odoo reviewed Sep 22, 2025

View reviewed changes

content/applications/hr/payroll/payroll_localizations/united_states.rst Outdated Show resolved Hide resolved

cas-odoo reviewed Sep 22, 2025

View reviewed changes

content/applications/hr/payroll/payroll_localizations/united_states.rst Outdated Show resolved Hide resolved

cas-odoo reviewed Sep 24, 2025

View reviewed changes

content/applications/hr/payroll/payroll_localizations/united_states.rst Outdated Show resolved Hide resolved

cas-odoo reviewed Sep 24, 2025

View reviewed changes

content/applications/hr/payroll/payroll_localizations/united_states.rst Outdated Show resolved Hide resolved

cas-odoo reviewed Sep 24, 2025

View reviewed changes

content/applications/hr/payroll/payroll_localizations/united_states.rst Show resolved Hide resolved

cas-odoo reviewed Sep 24, 2025

View reviewed changes

content/applications/hr/payroll/payroll_localizations/united_states.rst Outdated Show resolved Hide resolved

larm-odoo force-pushed the 19.0-payroll-add-us-localization-larm branch from 37c7dc1 to 2f834b9 Compare September 25, 2025 19:46

cas-odoo reviewed Sep 25, 2025

View reviewed changes

[ADD] Payroll: Add United States Localization

4ae73df

Felicious force-pushed the 19.0-payroll-add-us-localization-larm branch from 2f834b9 to 4ae73df Compare September 28, 2025 23:11

Felicious approved these changes Sep 28, 2025

View reviewed changes

robodoo closed this in 3ad4b7d Sep 29, 2025

robodoo temporarily deployed to merge September 29, 2025 02:22 Inactive

fw-bot mentioned this pull request Sep 29, 2025

[ADD] Payroll: Add United States Localization #14701

Closed

	- :guilabel:`Name`: Enter the business name in this field.
	- :guilabel:`Company Name`: Enter the business name in this field.

	- :guilabel:`Tax ID`: Enter the business's :abbr:`Employer identification number (EIN)`.
	- :guilabel:`Tax ID`: Enter the company's :abbr:`EIN (Employer Identification Number)`.

	940`. CLick the :guilabel:`New` button, and a new :guilabel:`Form 940` report page loads. Configure
	940`. Click the :guilabel:`New` button, and a new :guilabel:`Form 940` report page loads. Configure

	The CSV file summarizes the employee worked hours during a specified time period, correlating to
	The CSV file summarizes the employee's worked hours during a specified time period, correlating to

	:ref:`Iinstalled <general/install>`.
	:ref:`installed <general/install>`.

		:doc:`United States fiscal localization documentation
		<../../../finance/fiscal_localizations/united_states>`

[ADD] Payroll: Add United States Localization #14614

[ADD] Payroll: Add United States Localization #14614

Uh oh!

Conversation

larm-odoo commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robodoo commented Sep 19, 2025

Uh oh!

larm-odoo commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

larm-odoo commented Sep 22, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

larm-odoo commented Sep 25, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Felicious commented Sep 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What I changed (brief summary):

What I still need from you, @larm-odoo!

Spot-check focus areas

Uh oh!

Felicious commented Sep 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

larm-odoo commented Sep 19, 2025 •

edited

Loading

larm-odoo commented Sep 19, 2025 •

edited

Loading

Felicious commented Sep 28, 2025 •

edited

Loading