How Frappe HR gratuity rules work and when you need them
If your organization employs staff in a region where gratuity or end of service pay is owed, you need a way to calculate that amount accurately every time someone leaves after multi-year service. In Frappe HR, that calculation is driven by gratuity rules that you define, not by a spreadsheet kept beside the payroll run. Each rule holds the service slabs that set how many days or months of pay are earned for each band of years worked, along with the salary components that form the base for the calculation. Because the base is built from components, the way you have structured earnings in your salary structures directly determines the gratuity figure. A basic-only base and a basic-plus-allowances base can produce very different results, so the component choice is a decision for HR and finance to make together before the first exit is processed.
The result of a gratuity calculation can flow in two directions. It can be carried into a payroll run as an earning, or it can be recorded through a separate entry so it does not sit inside a regular monthly salary slip. The right route depends on how your finance team wants the payout reported, how it is taxed locally and whether the amount should appear alongside the final settlement. Frappe HR documentation describes these options, but the rule logic itself, including eligibility conditions, the minimum service period, the cap on the amount and how partial years are handled, must be confirmed against the labor law that applies in each country or region where you operate. Ask your legal or employment counsel to sign off on the rule design, and keep that sign-off with the configuration record so auditors can trace each rule to its source.
Gratuity configuration options and when each fits
This table compares the main design choices for Frappe HR gratuity: rule scope, slab structure, salary base and payment route. Read each row as a decision, then check the trade-off in maintenance and audit trail against your own headcount and legal obligations. The main takeaway is that the fewer rule variants you maintain, the less configuration drift you will need to explain to auditors.
| Decision | Option | Trade-off and maintenance | When it fits |
|---|---|---|---|
| Rule scope | One gratuity rule per region or country | Fewest rules to maintain and review. Each rule must still be checked whenever local labour law changes. | Single-country or single-jurisdiction employers with one statutory formula for all staff |
| Rule scope | Separate rules per employee group | Matches contracts that differ by grade, union or category. Every new group adds a rule to test and an assignment to keep correct. | Organizations with several contract types under the same country law |
| Slab definition | Fixed years-of-service slabs with one fraction per slab | Simple to audit because each slab maps to a single formula. Boundary cases such as partial years need an explicit rounding rule. | Plans where the statute or policy states a clear fraction of salary per service band |
| Slab definition | Cumulative slabs with a maximum cap | Captures caps on total payout. Caps must be reviewed whenever the policy or statutory limit changes. | Employers that must limit the total amount payable regardless of service length |
| Salary base | Basic salary only | Fewest components to map and simplest to reproduce. Can understate payout if the law or contract uses a wider wage definition. | Where the governing rule or contract defines the base as basic pay |
| Salary base | Defined set of salary components | Requires a documented list of included components and a check that each one is tagged correctly in salary structures. Errors in structure changes flow into gratuity. | Where allowances such as fixed housing or transport are part of the statutory wage |
| Payment route | Through a salary slip in the payroll run | Keeps payment, tax treatment and accounting in one payroll run. Harder to reconcile when the exit date falls mid-cycle. | Gratuity paid with a regular month-end payout and the exit occurs in a normal cycle |
| Payment route | Separate gratuity or full and final entry | Gives a stand-alone record per exit, which helps audit trail and dispute handling. Needs its own review step and accounting check. | Exits settled outside the monthly run or when the payout is reviewed by a different approver |
Setting up gratuity rules in Frappe HR step by step
This sequence takes gratuity from a legal question to a tested configuration, so that each rule, slab and payout path in Frappe HR matches the policy your counsel has confirmed and the figures your payroll team can check by hand.
Confirm the legal basis for each region
Before anyone opens Frappe HR, have counsel or your employment advisers confirm, for each country and state where you employ people, how gratuity or end of service pay is calculated: eligible service, the wage base, the rate per year of service, caps and the treatment of partial years. Record the answers in one document with the source for each rule. You know this step is done when every region in your headcount has a signed-off rule set and someone can name the owner of any future change.
Define salary components and the gratuity base
Work out which earnings count toward the gratuity base, such as basic pay alone or basic plus fixed allowances, and create those as earning components in Frappe HR with the correct abbreviations and formulas. Check that each component is included in the salary structures that apply to the affected employees. Confirm the base with a sample salary slip: the amount the components produce should match the figure from your manual calculation. Do not finish this step until the base for a test employee reconciles exactly.
Create the gratuity rule and service slabs
In the Gratuity Rule for each region, enter the slabs from your legal review: the service years at which each rate applies, the days or fraction of salary per year, the cap, and the base component you defined in the previous step. Keep one rule per distinct legal regime, not one rule for every department. Save the rule and open the slab table to confirm the boundaries, especially the exact year at which a slab changes. Done means the rule saves without errors and the slab table matches your legal document line by line.
Assign rules to employees
Link each employee to the correct gratuity rule, normally through the employee record or the salary structure assignment, depending on how your team has set up the data. Run a report or list view filtered by rule to confirm that every employee in a region carries that region's rule and that no one is left unassigned or assigned to a rule from another country. Note any exceptions, such as employees on contracts that follow different terms. Done means the assignment list reconciles with your headcount by region.
Test with sample leavers
Create test leavers, either copies of real records in a staging site or illustrative employees, with joining dates and exit dates that cover a short tenure, a boundary year and a long tenure. Run the gratuity calculation for each and compare the result with a manual worked example prepared by your payroll team using the same inputs. Record any difference and trace it to the rule, the base or the service calculation before you continue. Done means every test case matches the manual figure to the cent or fils, and the test set is saved for reuse after rule changes.
Choose the payout path
Decide whether gratuity is paid through a regular payroll run as an additional component on the final salary slip, or as a separate entry that settles only the gratuity amount. Confirm the choice against your tax treatment and the payout timing in your legal review, and set up the accounting entries and payable accounts that the chosen path needs. Run one test payout through a staging company or a dummy bank file and reconcile the ledger entries against the test calculation. Done means the chosen path produces one posting per leaver, the ledger balances, and your payroll lead has signed off the process document.
Access, audit and data protection for end of service records
Gratuity and end of service records combine salary data, personal data about leavers and money that leaves the company. The cards below cover who may change the rules, how payouts get approved, how calculations are kept, how leaver data is handled and how amendments are tracked.
Restrict who can edit rules and slabs
Gratuity rules, region-specific settings and service slabs drive every payout, so editing them should sit with a small group of HR administrators, not with everyone who can open the HR module. Review the role permissions on the gratuity and salary component doctypes, and confirm that payroll users can read the rules without being able to change them. Check who holds System Manager, since that role can bypass most restrictions.
Approval before any payout
A gratuity amount should be reviewed and approved by someone other than the person who calculated it before it reaches a payment or accounting entry. Use document status and the workflow your team configures to hold the record until approval is recorded. Confirm which roles can submit the final document and whether that action can be reversed, and test the flow with a sample leaver before go-live.
Retain calculation records
Keep the inputs behind each gratuity figure: the joining and leaving dates used, the basic pay snapshot, the slab applied and the rule version in force. Without these, a later query about a payout cannot be answered from the system. Confirm with your legal and finance advisers how long these records must be held in your jurisdiction, and set your backup and archive policy to match that period.
Protect personal data of leavers
Exit records contain national identifiers, bank details, salary history and sometimes reasons for leaving. Limit read access to the people who handle settlements, mask bank fields in list views where your setup allows it, and confirm how leaver records are retained or anonymized after the statutory period. Ask your data protection officer to review what a leaver's record holds before rollout.
Track changes to rules
When a gratuity rule or slab changes, the team needs to know which leavers were calculated under the old version and which under the new one. Version control for the rule setup is not automatic in every configuration, so decide whether changes are made through a Git-tracked customization export, a change ticket or both. Record who approved each change and the effective date it applies from.
Questions buyers ask before hiring help with gratuity
What drives the cost of a gratuity implementation in Frappe HR?
The main drivers are the number of regions or legal entities that need their own gratuity rules, how complex those rules are, the quality of your salary history, and how much testing the rules need before payroll relies on them. Each region adds a rule set to design, configure and verify. Complex rules, such as different treatment for resignation, termination, or death, add formulas and test cases. Messy salary history means more time reconciling past components before any calculation can be trusted. Ask any partner to price each of these drivers separately in the written scope.
How long does gratuity setup usually take?
Duration follows the same drivers as cost: how many regions and entities are in scope, how many rule variations exist, how clean the leaver and salary data is, and how many test payouts your finance and HR teams want to review before go-live. Timing also depends on how quickly your legal and HR owners confirm the rules and on your payroll calendar, since you will want the first live run to avoid a busy cycle. Ask for the timeline as part of the written scope rather than relying on a general estimate.
What do we need to supply before work starts?
You need to supply three things. First, written gratuity rules from your legal or HR advisers for each region, including the qualifying service period, the days or months of pay per year of service, caps, and how partial years and different exit reasons are handled. Second, the salary structures and components that define the basic pay used in the calculation, with their effective dates. Third, a leaver history export with joining dates, exit dates, exit reasons and any past gratuity payments. Incomplete inputs are the most common cause of delay, so confirm each item with your advisers early.
Who is responsible for the legal interpretation of gratuity rules?
Your legal and HR advisers remain responsible for interpreting the law and your contracts. The implementation partner configures Frappe HR to match the rules you have approved in writing and tests that the system produces the expected results. DeployOpen prepares systems, controls and evidence for compliance reviews, but it does not issue audit reports, attestations or certifications, and independent auditors and certification bodies perform those assessments. Put the ownership split in the scope document so that each rule has a named approver.
Can our in-house HR or payroll team implement gratuity rules without a partner?
Often yes, if your team already runs Frappe HR payroll and has someone comfortable with salary components, formulas and Frappe HR document settings. The work is configuration and testing rather than custom code in most cases, but it still needs careful verification across each region and each exit reason. Consider whether the team has time to test thoroughly before a payroll run, and whether it can maintain the rules when laws or policies change. A written scope lets you compare doing it internally with an outside quote on equal terms.
How does fixed-scope pricing work for gratuity work?
Most DeployOpen engagements are fixed-scope, so scope, deliverables and timelines are agreed in writing before work starts. The quote follows from that written scope, which should list the regions, the rule sets, the salary components involved, the exit scenarios, the data migration or cleanup tasks, and the test cases to be run. Any change to these items should be handled as a written scope change. Ask for each deliverable and its acceptance criteria to appear in the document, so you can see what is included and what is not.
What goes wrong with gratuity calculations, and how do we check them?
The most frequent failures are wrong basic pay, because the wrong salary component is used as the base, incorrect service calculation around leap years or break-in-service periods, and caps or exit reasons that were not mapped correctly. Check each rule with test employees whose expected amounts were calculated by hand from the approved rules, covering both short and long service and every exit reason. Keep those test cases as evidence, and rerun them after any change to salary structures or Frappe HR updates. Confirm the exact behavior of the version you run with the Frappe documentation.
What your HR and finance teams must provide
Gratuity configuration is only as correct as the decisions your HR and finance teams hand over before build starts. The most important is legal interpretation. Your employment counsel should confirm which statute or contract governs end of service payments for each region and employee group, how service is counted (continuous service, breaks, transfers between entities), how the qualifying wage is defined, and whether any cap applies. DeployOpen configures what you specify, so the written interpretation should exist before the Gratuity Rule and its slabs are entered, and it should name the person who signed it off.
HR must also supply approved salary bases. Decide which salary components count toward the gratuity wage, such as basic pay and fixed allowances, and which are excluded, then map each one to a salary component already defined in your salary structures. Finance should confirm the expense and liability accounts that gratuity provisions and payouts will post to, and who may approve a gratuity payment and up to what amount. Record these approvals in writing, because they determine how the Gratuity document and any payroll or separate entry are reviewed later.
Finance then owns the reconciliation. Before the first live run, agree how each gratuity payout will be matched to the general ledger entries it creates and to the bank payment that settles it, and who performs that check each period. Run a small set of illustrative leavers through the full cycle in a test site and compare the calculated amounts to a manual calculation signed by HR. Any difference should be resolved by changing the written rule, not by overriding figures in the live system. Confirm with your own auditors which evidence they will ask for, because DeployOpen prepares the records but does not issue any audit opinion.
How DeployOpen scopes gratuity work
The sequence turns gratuity policy into written rules, configured Frappe HR components and tested calculations that match agreed worked examples. Each step ends with a named output, so the scope, quote and handover all refer to the same artifacts.
Collect the policy and employee population
DeployOpen reviews the gratuity policy, employment contracts, collective agreements and any statutory text that applies to each country or region where you employ people. You provide the employee population by region, employment type and contract basis, plus a sample of recent leavers with their final salary and service dates. The step closes with a list of open policy questions that your HR and legal owners must answer in writing before configuration starts.
Write the scope of regions and rules
DeployOpen drafts a written scope that lists each region, the eligibility conditions, the service slabs, the salary basis for the calculation (such as basic pay or a defined set of components), the treatment of partial years, and the exclusions. Your HR, finance and legal owners approve the document, and it becomes the basis for the fixed-scope quote. The output is a signed scope document with deliverables and acceptance criteria for each region.
Configure salary components and region rules
DeployOpen builds the salary components that carry the gratuity basis, the formulas that compute the amount from service and salary, and the region-specific settings in Frappe HR. Where a rule depends on a leaving reason or a contract type, the configuration reflects that condition explicitly. Your team reviews the configuration in a non-production site before it is moved forward. The output is a configured site with components, formulas and rule settings that trace back to the approved scope.
Test against agreed worked examples
DeployOpen and your HR owner agree a set of worked examples during scoping, covering typical leavers, edge cases such as service at a slab boundary, partial years and mid-year salary changes. DeployOpen runs each example through the configured rules and records the expected and actual result side by side. Any difference is traced to a rule, a formula or an input, then fixed and retested. The output is a test record that shows every agreed example passing, with the exceptions you accepted in writing.
Decide payment route and run a pilot
Your finance and payroll owners choose whether gratuity is paid through a regular payroll run or through a separate entry, and DeployOpen configures the chosen route, including how the accounting entries post to ERPNext accounts. DeployOpen runs a pilot with a small number of historical or test leavers and checks the resulting slips or entries against your existing manual calculations. The output is a pilot report that records the route, the accounting postings and any variances you chose to accept.
Hand over documentation and train owners
DeployOpen documents each configured rule, the worked-example test set, the payment route, the accounting postings and the steps to add a new region or change a slab. Your HR and payroll owners are trained to run a gratuity calculation and to read the resulting records. The output is a handover pack with the documentation, the test set and a record of training, which your team can use without DeployOpen present.
Agree on rule changes through a retainer
Gratuity rules change when labor law, collective agreements or company policy changes. DeployOpen can maintain the rules under a retainer, with changes scoped in writing, configured, tested against updated worked examples and handed over again. Quotes for any change follow the written scope for that change. The output is a change record that links each rule revision to the approved policy text and to the test results that confirm it.
How DeployOpen works on this
DeployOpen plans, builds and documents Frappe HR gratuity rules and end of service payments inside your own infrastructure, starting from your employment contracts and gratuity policy. Each engagement is fixed-scope, with the rule set, test cases and handover agreed in writing before configuration begins.
How we scope
- Collect the gratuity clauses from employment contracts, policies and applicable labour rules for each country or region you employ people in.
- Map each region to its service slabs, salary components for basic pay and allowances, and the eligibility rules for resignation, termination and death.
- Agree in writing which payment paths are in scope: payroll run, separate gratuity entry, or both, along with the accounting accounts to post to.
How we build
- Configure salary components and gratuity rule records per region, with effective dates so changed policies do not rewrite past settlements.
- Build test employees covering edge cases such as breaks in service, partial years and changes of salary during service, and check each calculated amount.
- Verify that payouts post correctly to ERPNext accounts and appear on the expected salary slip or full and final statement.
How we hand over
- Document each gratuity rule, its inputs, its effective dates and the approver who signs off on changes.
- Walk your HR and finance teams through the monthly and leaver workflows, using the test cases as a repeatable checklist.
- Hand over the configuration export and documentation so your team can add a region or change a slab without starting again.
How we support
- Ongoing support, upgrades and testing of gratuity configuration are available as a retainer after handover.
- Review the rules again when Frappe HR or ERPNext releases change payroll or leave behavior that your gratuity logic depends on.
- Ask your legal or employment advisers to confirm each rule. DeployOpen configures what you approve and does not give legal advice.
