How Frappe HR salary structures and salary components define pay
A salary structure in Frappe HR is the template that tells the payroll engine which earnings and deductions apply to a group of employees and how each amount is calculated. Salary components are the individual earning and deduction lines, such as basic pay, housing allowance, provident fund contribution or professional tax. Formulas and conditions on each component determine the amount, and a salary structure assignment links a specific employee to one structure from a given effective date. If pay rules do not match your written policies before the first payroll run, every salary slip after it inherits the error, so this design work belongs before any employee is loaded into payroll. Plan it with HR and finance together, because each component you define will later post to ERPNext accounts.
Expect the design to change. Allowances get revised, grades get reorganized and statutory rates move. The safe pattern is to version structures by effective date rather than edit a live structure in place, so that slips already generated keep the rules that applied to them. Decide early which components are fixed, which are variable and which depend on attendance or leave, because that choice determines whether a mid-year revision needs a new assignment, an arrears entry or only a component change. Tax-related components need particular care: if a structure is swapped mid-year, the tax calculation for the year must still reflect earnings already paid, so confirm the approach with your tax adviser before the change goes live.
Field names, child table layouts and the behavior of formulas and assignment dates are governed by the Frappe HR documentation for your installed version, and they can differ between releases. Before you finalize the design, confirm them on a non-production site and run test slips for at least one employee per structure, including one mid-year change. Ask your implementation partner to document each component's formula, its accounting mapping and the assignment rule in writing, so the design can be audited and handed over without relying on one person's memory.
Structure design options and when each fits
This table compares the main structure design choices in Frappe HR across maintenance effort, reporting clarity and tax handling. Read each row as a decision: the left column names the choice, and the cells show what it costs you later and when it suits your pay policy. The main takeaway is that fewer structures are easier to maintain, but employee groups with different rules usually need their own structure.
| Design choice | Trade-off in maintenance and reporting | Tax handling and when it fits |
|---|---|---|
| Single structure for all employees | Lowest number of components to maintain. Reports blend groups, so filtering by location or grade needs extra report filters. | Works only when every employee has the same earnings, deductions and tax treatment. Tax-exempt allowances usually break this model. |
| Multiple structures by employee group | More structures to keep in step when a rule changes. Each group's slips and accounts are easier to read separately. | Lets each group carry its own tax-relevant components, such as allowances for a specific region or contract type. Choose it when groups differ in tax treatment. |
| Earnings-only structure | Simple to build and review. Deductions such as provident fund, insurance or loans are handled elsewhere, which can split the slip review. | Suits roles where all deductions are computed outside payroll. Confirm with your payroll adviser where statutory deductions belong. |
| Earnings and deductions in one structure | Every deduction sits beside the earnings it depends on, so one review shows net pay. Changes must be tested against both sides. | Keeps statutory deductions and tax inputs in the same slip, which makes tax computations easier to audit. Preferred when deductions depend on earnings. |
| Fixed-amount components | Easiest to understand and audit. Every revision means editing amounts on the structure or assignment. | Tax effect is simple to trace when the amount is fixed. Revisions mid-year still need a review of tax slabs and declarations. |
| Formula-based components | Automatically reflects base pay changes, reducing manual edits. Formulas need testing and documentation so later editors can follow them. | Useful for percentages of basic pay or statutory caps. Confirm each formula's result on sample employees before the first live run. |
| Monthly payroll frequency | Matches the most common pay cycle, so structures, tax slabs and reports align with one run per month. | Tax calculations are usually set up around the monthly cycle. Check how your jurisdiction's annual tax rules apply before choosing another frequency. |
| Other payroll frequencies (for example, weekly or biweekly) | Changes proration, leave and attendance inputs, and period-based components. Expect more testing before go-live. | Annualized tax logic can behave differently from monthly setups. Ask your tax adviser to confirm how each frequency is treated. |
How to set up components, structures and assignments
This sequence turns a pay policy into tested Frappe HR configuration: components with correct accounting, formulas checked against hand calculations, structures per employee group, effective-dated assignments, and a dry run that proves the salary slips before any money moves.
Map pay elements to components and accounts
Before opening Frappe HR, list every earning, deduction and employer contribution in your pay policy and decide which ones become Salary Components. For each one, record whether it is taxable, whether it is pro-rated for leave or unpaid days, and which ERPNext account it posts to, such as a salary expense, a payable or a statutory liability account. Ask your finance lead to sign off this map, because the accounting treatment is hard to change once payroll entries exist. The step is done when the map covers every line on a sample payslip and each row has an account assigned.
Create salary components with their settings
Create each Salary Component in Frappe HR using the map from the previous step. Set the type to earning or deduction, choose the accounting fields, and mark components that are statutory or that affect gross pay for other calculations. Keep names short and stable, because formulas and reports reference them by name, and renaming later means updating every formula that uses it. The check is a component list that matches your map one to one, with no duplicates and no component left without an account.
Write formulas and test them on sample employees
Write the amount or formula for each component, using base salary and other components as inputs. Create two or three sample employees in a test company that represent typical cases, such as a full-month employee, a new joiner and an employee with unpaid leave. Preview the salary slip for each one and compare every component against a calculation done by hand from the same inputs. If a result differs, check rounding, the order in which components are evaluated and whether a dependent component is missing. The step is complete when every formula matches the hand calculation for all sample cases.
Build salary structures for each employee group
Create one Salary Structure per pay model, such as monthly salaried staff, hourly staff or a contractor group, and add the components in the order they should calculate. Set the payroll frequency on each structure so it matches how the group is paid. Where a component should appear only for some staff, use conditions instead of duplicating the structure. The check is a structure per group, each one previewed against a sample employee, with no component appearing that the policy does not call for.
Assign structures with effective dates
Create a Salary Structure Assignment for each employee, linking the employee to the structure, the base salary and a start date that matches the pay change. Use a new assignment for each revision rather than editing an old one, so the history stays intact for past salary slips and reports. Confirm with HR that the effective dates match approved letters. The check is a per-employee history showing one active assignment for each period, with no overlaps and no gaps.
Confirm tax and statutory links before a mid-year change
If your structures feed income tax or statutory deductions, confirm that the tax slabs and tax-related components are linked through the assignment, not only through a manual field. Ask your payroll advisor which assignments need the new effective date when a mid-year revision is applied, so year-to-date tax is not recalculated from the wrong starting point. Test one mid-year revision on a sample employee and check that the year-to-date totals on the slip move in the expected way. The step is done when the revised sample produces the cumulative figures you calculated by hand.
Run a dry payroll and review the salary slips
Create a Payroll Entry for a test period covering a sample of real employees, and generate salary slips without submitting them. Review each slip against the approved pay record, checking gross, each deduction, net pay and the accounting lines that would post. Ask someone outside the build team to review a few slips, because they will spot labels and totals the builder has stopped noticing. Fix any mismatch at the component, formula or assignment level, then regenerate. The sequence is complete when the dry run matches the expected pay for every reviewed slip and the accounting preview matches the account map.
Changing a structure mid-year without breaking tax calculations
Revise pay by creating a new Salary Structure Assignment with a later from_date, never by editing the assignment already in force. Salary slips for earlier months were calculated from the earlier assignment, and they are the record that payroll, auditors and the employee will compare against. If a past assignment is changed, reopening or recalculating an old slip can silently produce different earnings and deductions, and the year's history no longer shows what was actually paid in each period. Keep one assignment per effective change, and confirm in your version how overlapping dates are validated so that two assignments cannot both apply to the same month.
The tax side depends on the same dated record. Income tax slabs and employee tax exemptions are linked through the structure assignment, so the new assignment must point to the slab set and exemption treatment that apply from its effective date. In the Frappe HR tax computation, withholding for a financial year is worked out on a projected annual basis, which means a mid-year raise changes the tax deducted from every remaining month, while tax already deducted in earlier months stays where it was. Before go-live, confirm with your payroll owner how year-to-date tax is carried forward in your version, whether exemption declarations submitted under the old assignment still apply, and which slab effective date the new assignment will use. The mechanics of slab setup are covered in the income tax slabs topic.
Test the revision against a prior period before it touches live payroll. In a copy of the site, create the new assignment for one employee with a salary that differs from the original only by the revised amount, then generate a salary slip for a closed earlier month and compare each earning, deduction and tax line with the slip the employee actually received. Unchanged months should match line for line, and any difference should trace back to the revision. Repeat the test for an employee with an exemption declaration and one with a tax-slab change, since those are where tax errors usually appear. Retroactive revisions are a separate case: once a change is approved for a month that is already paid, the catch-up goes through the arrears process covered in the arrears topic, not through back-dating the assignment.
Who can change pay rules and how changes are controlled
Salary structures, components and assignments decide what every employee is paid and how tax is computed, so edit rights need the same care as the payroll run itself. The cards below cover who should hold each permission, how HR and finance keep each other in check, how edits are traced, and which script controls apply in your Frappe HR deployment.
Role-based access to pay setup
Frappe HR and ERPNext permissions are set per DocType, so salary structures, salary components and salary structure assignments can each carry their own roles. Decide which roles can create, submit, amend and cancel each one before go-live, not after the first payroll. Check that payroll users who run salary slips cannot also rewrite the structure those slips draw from. Test the matrix with a non-admin test account, since administrators bypass most of these checks.
Separating HR and finance approval
HR usually owns who earns what, while finance owns the ledger entries that payroll posts. Keeping those two duties with different people means a change to a salary structure needs HR sign-off and a separate finance check on the resulting accounting entries. Write the split down as a control, name the approver for each change type, and confirm that no single user holds both the structure edit role and the payroll journal approval role.
Audit trail of structure edits
Frappe records document version history, so you can see who changed a salary structure or assignment and when. Confirm that submitted documents are amended rather than overwritten, and that amendments keep the original for comparison. Pair this with a written reason field or a change request reference, because the version log shows what changed but not why. Review the trail at each payroll close, not only after a dispute.
Restricting visibility of pay data
Salary amounts are sensitive even to managers who may approve leave or expenses for the same people. Limit salary slip and salary structure assignment visibility with User Permissions tied to company or department, and check that reports, list views and exports do not reveal figures to users outside that scope. Ask your Frappe partner to test these views with a manager account and an HR account before live data is loaded.
Server script controls on pay logic
Formulas in salary components can be extended with Server Scripts, which run Python on document events. From version 15, these are disabled by default and must be enabled with the server_script_enabled setting. Frappe Cloud public shared benches do not allow them, so a custom pay calculation there is not an option. Decide who may enable the setting, record that decision, and treat any script that changes pay as code requiring review and version control.
Questions buyers ask about Frappe HR salary structures
What drives the cost of designing salary structures in Frappe HR?
The cost follows the number of pay rules you need to model, not the number of employees. Each earning and deduction component, each formula that depends on basic pay, attendance or grade, and each region or entity with its own statutory rules adds design, build and test work. Pay structures for one country with a few grades are far smaller than a multi-entity structure with overtime, allowances tied to location and separate contractor pay. Ask any partner to price the components, formulas and structure assignments separately so you can see where the effort sits. The work is quoted as a fixed scope from a written list of deliverables, and it is largely one-time, with later changes billed as new work.
How long does salary structure work usually take?
Duration depends on how many structures you need, how clean your current pay data is, and how many approvals the payroll rules require. Work usually runs in this order: gather the pay policy, map components to your ledger accounts, build and test formulas against sample employees, then run parallel payroll cycles before go-live. Each step waits on a decision from HR or finance, so late answers extend the schedule more than technical work does. Request a timeline in the written scope that names the decision owners and the dates they must respond by. No duration applies until that scope is agreed.
What do our HR and finance teams need to provide before the build?
HR owns the pay policy and finance owns the accounting treatment. HR needs to supply the pay elements for each grade, the rules for overtime, allowances and deductions, the payroll frequency, and the list of employees in each structure. Finance needs to confirm which ledger accounts receive each earning and deduction, how payables to employees and authorities are settled, and who approves a salary slip before payment. Both teams should also provide a set of anonymized sample cases with expected net pay, because those cases become the test cases that prove the formulas are correct.
Can our internal team design Frappe HR salary structures without a partner?
Yes, a team with Frappe HR and ERPNext experience can build salary structures in-house, and the documentation and the open-source code are available to do it. The risk lies in the testing and in the rules that change over time. An internal team should have a named payroll owner, a written test set with expected results, and a process for checking formulas after each release of the Frappe HR app. A partner can take on the design, build and verification as a fixed-scope piece, which leaves your team to own approvals and day-to-day payroll. Decide based on who will maintain the rules after the first cycle.
How do we request a fixed-scope quote for this work?
Send a written brief that lists the structures, the grades or designations covered, the components with their formulas, the countries and entities, the payroll frequency, the ledger mapping and the number of employees per structure. Ask the provider to state the deliverables, the testing approach, the items the client must provide, the acceptance criteria and what is excluded. DeployOpen works from a written scope agreed before work starts and quotes from that scope, and it does not publish a price list. Compare quotes on the same scope items, and confirm whether statutory rules such as tax slabs are included or handled in a separate engagement.
How do we change a salary structure mid-year without breaking tax calculations?
Do not edit an existing structure assignment in place. Create a new assignment with a new effective date, so earlier salary slips keep the values they were calculated with and the income tax computation for the year can still be traced. Confirm that the tax slabs and exemption declarations linked to the assignment apply from the new date. Test the change on a sample employee, compare the year-to-date tax result with and without the change, and only then roll it out. Revisions approved after their effective date raise a separate arrears question, which should be handled through the arrears process.
What goes wrong most often with salary components and formulas?
The most common faults are formulas that reference a component before it is calculated, rounding that differs from the payroll policy, and components with no ledger account, which cause salary slips to post incorrectly. Structures also break when a component is renamed or deleted while assignments still refer to it. Test each formula with edge cases such as joiners in mid-month, leavers, unpaid leave and zero basic pay. Keep a record of every formula version so that a disputed payslip can be traced to the rule that produced it.
Where to confirm component and structure behavior
Before you finalize a pay design in Frappe HR, confirm how salary components, formulas and structure assignments behave in the exact version you will run. Start with the supported versions page, which lists the end-of-life and support windows for ERPNext and Frappe Framework. Plan against a version that is still supported, because a payroll design built on a release that is ending support leaves you with an upgrade inside the payroll year. Confirm the version number in your own environment rather than assuming it matches the documentation you are reading.
Next, read the ERPNext documentation and the Frappe HR source in the frappe/erpnext repository for the branch that matches your installed version. Check the behavior of the Salary Component, Salary Structure, Salary Structure Assignment and Payroll Entry doctypes, paying particular attention to how formulas are evaluated, how base and variable amounts are handled and whether changes to a structure affect slips already generated. The releases page shows minor releases that change payroll behavior, so note the release you tested against. Record your findings in the design document so that the next person who changes a structure knows what was verified and on which version.
Finally, test a mid-year change in a non-production site before it reaches live employees. Create a structure revision, assign it with an effective date and generate a salary slip for a sample employee. Confirm that the earnings, deductions and tax lines match your expectations and that prior slips remain unchanged. Ask your implementation partner or your Frappe HR contact to confirm any behavior you cannot verify in the documentation, and keep that confirmation in writing alongside your test results.
How DeployOpen scopes and delivers salary structure work
DeployOpen plans, implements, customizes, tests and documents Frappe HR salary structures and salary components inside your own infrastructure. Engagements start from a written, fixed scope, so the pay design, the test cases and the handover are agreed before any build work begins.
How we scope
- Inventory of earnings, deductions and employer contributions your payroll currently pays, with the rule behind each one
- Agreed list of salary structures by employee group, with assignment rules and the effective dates they will use
- Written statement of which tax, statutory and gratuity calculations are in scope and which remain with your payroll advisers
How we build
- Component definitions and formulas built and reviewed against your sample employees before any structure is released
- Structure assignments and payroll frequency configured, with test payroll runs in a staging site you control
- Mid-year revision procedure written and rehearsed so changed structures do not break tax calculations already in progress
How we hand over
- Test evidence per component showing expected and calculated values for each sample case, kept with the scope record
- Runbook for payroll administrators covering adding components, revising structures and reversing a wrong assignment
- Knowledge transfer session with your HR and finance staff, with configuration exported under version control
How we support
- Ongoing support, upgrades and regression testing for salary structures available as a retainer after handover
- Review of salary structure changes before each payroll cycle, including changes driven by new ERPNext or Frappe HR releases
- Documented change requests that follow the same scope, test and handover steps as the original build
