ranbot-ai/skills/odoo-hr-payroll-setup

Odoo HR & Payroll Setup

Overview

This skill guides HR managers and payroll accountants through setting up Odoo HR and Payroll correctly. It covers salary structure creation with Python-computed rules, time-off policies, employee contract types, and the payroll → accounting journal posting flow.

When to Use This Skill

• Creating a salary structure with gross pay, deductions, and net pay.
• Configuring annual leave, sick leave, and public holiday policies.
• Troubleshooting incorrect payslip amounts or missing rule contributions.
• Setting up the payroll journal to correctly post to accounting.

How It Works

1. Activate: Mention @odoo-hr-payroll-setup and describe your payroll scenario.
2. Configure: Receive step-by-step setup for salary rules and leave allocation.
3. Debug: Paste a salary rule or payslip issue and receive a root cause analysis.

Examples

Example 1: Salary Structure with Deductions

Menu: Payroll → Configuration → Salary Structures → New

Name: US Employee Monthly
Payslip Code: MONTHLY

Rules (executed top-to-bottom — order matters):
  Code  | Name                   | Formula                        | Category
  ----- | ---------------------- | ------------------------------ | ---------
  BASIC | Basic Wage             | contract.wage                  | Basic
  GROSS | Gross                  | BASIC                          | Gross
  SS    | Social Security (6.2%) | -GROSS * 0.062                 | Deduction
  MED   | Medicare (1.45%)       | -GROSS * 0.0145                | Deduction
  FIT   | Federal Income Tax     | -GROSS * inputs.FIT_RATE.amount| Deduction
  NET   | Net Salary             | GROSS + SS + MED + FIT         | Net

Federal Income Tax: The standard Odoo US localization does not expose a single l10n_us_w4_rate field. Use an input (salary input type) to pass the withholding rate per employee, or install a community US payroll module (OCA l10n_us_hr_payroll) which handles W4 filing status properly.

Example 2: Configure a Time Off Type

Menu: Time Off → Configuration → Time Off Types → New

Name: Annual Leave / PTO
Approval: Time Off Officer
Leave Validation: Time Off Officer  (single approver)
  or: "Both" for HR + Manager double approval

Allocation:
  ☑ Employees can allocate time off themselves
  Requires approval: No

Negative Balance: Not allowed (employees cannot go negative)

Then create initial allocations:
Menu: Time Off → Managers → Allocations → New
  Employee: [Each employee]
  Time Off Type: Annual Leave / PTO
  Allocation: 15 days
  Validity: Jan 1 – Dec 31 [current year]

Example 3: Payroll Journal Entry Result

After validating a payroll batch, Odoo generates:

Debit   Salary Expense Account     $5,000.00
  Credit  Social Security Payable     $310.00
  Credit  Medicare Payable             $72.50
  Credit  Federal Tax Payable         (varies)
  Credit  Salary Payable           $4,617.50+

When net salary is paid:
Debit   Salary Payable            $4,617.50
  Credit  Bank Account              $4,617.50

Employer taxes (e.g., FUTA, SUTA) post as separate journal entries.

Best Practices

• ✅ Do: Install your country's payroll localization (l10n_us_hr_payroll, l10n_mx_hr_payroll, etc.) before building custom rules — it provides pre-configured tax structures.
• ✅ Do: Use salary rule inputs (inputs.ALLOWANCE.amount) to pass variable values (bonuses, allowances, withholding rates) rather than hardcoding them in the rule formula.
• ✅ Do: Archive old salary structures rather than deleting them — active payslips reference their structure and will break if the structure is deleted.
• ✅ Do: Always set an active Employee Contract with correct dates and salary before generating payslips.
• ❌ Don't: Manually edit posted payslips — cancel and regenerate the payslip batch if corrections are needed.
• ❌ Don't: Use contract.wage in deduction rules without verifying whether the structure is monthly or annual — always check the contract wage period.

Limitations

• Odoo Payroll is Enterprise-only — the Community Edition does not include the Payroll module (hr_payroll).
• US-specific compliance (W2, 941, state SUI/SDI filing) requires additional modules beyond the base localization; Odoo does not generate tax filings directly.
• Does not cover multi-country payroll (employees in different countries require separate structures and localizations).
• Expense reimbursements via payslip (e.g., mileage, home office) require a custom salary rule input and are not covered in standard HR Payroll documentation.