Payroll — Employees and Pay Heads

The Payroll module is a paid add-on (₹550/month — see Add-ons). This doc covers the two foundations every pay-run depends on: Employees and Pay Heads.

Time to read: ~12 minutes. You’ll need: the Payroll add-on active on your tenant. During the free trial, it’s on automatically.

What you get when this is done

• A complete employee roster with bank details (encrypted), statutory IDs, designation, department.
• A pay-head catalog covering earnings, deductions, and statutory items, with formulas pre-loaded for India (PF, ESI, PT, TDS).
• Per-employee salary structures so monthly pay runs compute correctly without re-entering numbers.

Where to find the screens

From the sidebar (after the Payroll add-on is active):

• Payroll → Overview — high-level dashboard with pending pay-runs, statutory dues, recent payslips.
• Payroll → Employees — the roster.
• Payroll → Pay Heads — the component catalog.

These two screens are typically set up once and rarely touched after the first month, except to add new joiners or change salary structures.

Part A — Pay Heads (Components)

Pay Heads are the building blocks of every payslip: BASIC, HRA, PF, ESI, TDS, etc. Booksmor seeds 10 standard heads on first use; you can add, rename, or disable any of them.

The seeded pay heads

How formulas work

Booksmor uses a small Formula DSL for component calculations — no spreadsheets, no scripting:

A formula like pct:12 of:basic cap:15000 says: take 12% of BASIC, but cap the BASIC at ₹15,000 first if it’s higher. So an employee with BASIC ₹20,000 contributes ₹1,800 (12% of ₹15,000).

If a formula is malformed, the engine fails open — the component computes to zero rather than crashing the pay run. Check Pay Runs → recompute if a head looks wrong.

Editing or adding pay heads

Payroll → Pay Heads:

• Edit any non-system head — change name, formula, sort order.
• Disable a head you don’t use (it stops appearing on new salary structures).
• + Add pay head for company-specific items (e.g. “Meal allowance”, “Phone reimbursement”).
• System heads (the four statutory ones) are flagged — you can edit their formulas but you can’t delete them.

Adding a new pay head doesn’t affect existing salary structures. Add it to each employee’s structure manually, or use the bulk-update endpoint (planned).

Part B — Employees

The employee record is the source of truth for everything about each person on your payroll.

Add an employee

1. Payroll → Employees → click + Add employee (top right).
2. Fill in the form (Personal + Statutory + Salary structure sections):

Personal

• Name — full legal name.
• Code — your internal employee ID, e.g. EMP-001.
• Designation — job title.
• Department — for grouping in reports.
• Phone — contact, also useful for sending payslips.
• State code — 2-digit GST state code; drives PT formula and HRA exemption metro/non-metro logic.

Bank & payment

• Payment method — Bank transfer / Cash / Cheque / Other.
• Bank account number — encrypted at rest. After save, only the last 4 digits ever appear on screen (e.g. •••• 1234). The full number is never re-displayed; if you need to change it, edit the field and type the full new number.
• IFSC — your bank’s branch code.

Statutory IDs

• UAN (Universal Account Number) — 12-digit PF identifier. Soft-validated on save. Required for ECR generation.
• PF Member ID — your company’s PF member ID for this employee.
• ESI number — required for ESI filings.

Tax (TDS)

• Tax regime — new (default for FY 2026-27) or old. Drives the slab engine — see Tax (TDS) doc for declarations and side-by-side projection.

Salary structure

• A row per applicable pay head with monthly_value in rupees.
• Earnings + deductions appear in their respective sections.
• Set to 0 to skip a head for this employee (instead of removing the row, which would lose history).
• The salary structure can be edited any time; historical payslips reference the structure as it was at posting, so changing it now doesn’t rewrite older payslips.

3. Click Save.

The employee appears in the roster (active by default).

Editing or deactivating

• Open an employee → edit any field → Save.
• To deactivate (employee left the company), set Active to off. They drop to the bottom of the roster (dimmed) and don’t appear in new pay runs. Historical payslips remain accessible.

Managing 50+ employees

• The Employees page paginates and supports search.
• Bulk import is on the roadmap; for now, add new joiners one by one or contact support for a one-off import.

Common questions

The four statutory heads (PF/ESI/PT/TDS) — can I delete them? No. They’re flagged as system-required because Booksmor’s statutory pivot reports and government filings (ECR, 24Q, Form 16) read from these specific codes. You can disable them on individual employees’ salary structures (set the head’s row to 0), but the catalog entries stay.

Can I rename PF or change its formula? Yes. You can rename any head (e.g. PF → EPF) and edit the formula (e.g. uncap the wages for grandfathered employees, change the percentage). The filings still use the code to find the head.

What’s the difference between BASIC and the others? BASIC is the reference number for percentage formulas — pct:12 of:basic means 12% of the employee’s BASIC. By convention BASIC is 40–50% of total gross; HRA is then a percent of BASIC; SPECIAL fills the gap to the desired total CTC.

An employee just moved from Karnataka to Tamil Nadu — what changes? Update their State code on the employee record. The PT formula when:state==KA will stop firing for them on next pay run; if you have a TN-specific PT head set up similarly, it’ll start firing.

My bank account encryption — can I see the full number for verification? No, by design. After save, only last 4 digits show. This protects against insider snooping. If you need to verify the number, you’d have to ask the employee directly (or have them check their bank statement).

Can I track CTC separately from gross? Booksmor’s salary structure is monthly-component-based, not CTC-percentage-based. To use a CTC model, set each component’s monthly_value = (CTC annual ÷ 12 × component %). Document the CTC in the employee’s notes or a custom field.

How do I handle variable monthly pay (e.g. commission, OT)? Use Variable pay on the specific pay run — see Pay Runs doc. One-off earnings/deductions get added per-payslip without touching the salary structure.

Do salary changes mid-year prorate automatically? No — Booksmor uses the salary structure as-of the pay-run date. If an employee gets a raise on day 15, you’d run two pay runs (or use variable pay on the affected payslip).

Troubleshooting

Pay run shows ₹0 for a statutory head. Either the formula’s when: gate excluded the employee (e.g. ESI when gross > ₹21,000), or BASIC is 0, or the formula syntax is wrong. Edit the pay head, check the formula.

Bank account field rejects what I type. Booksmor accepts digits only (no spaces / dashes). Strip them and re-enter.

UAN warning “12 digits expected” on save. UAN is strictly 12 digits. If you don’t have it yet (new employee, UAN not generated), leave it blank — ECR will exclude them with a warning until you fill it in.

“Salary structure has no BASIC” error on save. A handful of formulas (HRA via of:basic, PF) need BASIC to compute. Even if BASIC is 0, the row must exist. Add a BASIC row with value 0 if you want to skip it.

Need more help? Email support@booksmor.com with the employee code (or name) and what’s misbehaving.