How ERPNext user permissions restrict records by company and territory
A single ERPNext site shared by several companies, territories or branches needs a way to stop one unit from seeing another unit's sales orders, stock entries or purchase invoices. In ERPNext, the mechanism for this is user permissions. A user permission ties a user to one value of a link field, such as a Company, Territory or Warehouse, and ERPNext then limits the documents that user can see to those whose linked field matches the value. User permissions are a separate layer on top of role permissions: the role decides which DocTypes a user can open and what actions they can take on them, while the user permission decides which records inside those DocTypes are visible. A user with read access to Sales Order still sees nothing from another company if no matching user permission exists for that company's values.
Teams typically need this layer when one site must keep entities apart for day-to-day work but still serve shared functions. Regional sales staff, branch stock controllers and company-specific accountants are common examples. Before you configure anything, list every DocType your users touch and confirm which link field on each one should drive the restriction. The documented behavior depends on those link fields, and a DocType that does not link to the dimension you are filtering on will not be restricted by it. Also confirm with your own test site how ERPNext applies user permissions to linked documents, because the outcome for each DocType can differ and should be verified rather than assumed.
Plan the permission model before loading production users. Decide which dimension is the primary boundary (company, territory or branch), who needs more than one value, and who needs no restriction at all. Note that user permissions only narrow what a role already allows, so a user with broad role access and no user permissions may see everything the role permits. Ask your ERPNext implementation partner to document the intended matrix of users, values and DocTypes, and to test it with a set of named test accounts before go-live. The official behavior and configuration steps are described in the ERPNext user permissions documentation, which should be the reference for your build.
Which user permission type fits each access model
This table compares the main ways to restrict a user with user permissions in ERPNext, from company and territory links to custom link fields. Read each row as a question: what does this restriction limit, when does it fit, and what does it cost you to set up and maintain. The main takeaway is that the permission type should follow how your data is linked, not how your org chart looks.
| Permission type | What it restricts | When it fits | Main trade-off |
|---|---|---|---|
| Company | Documents whose Company field matches the assigned value, and linked records that carry a company | Separate legal entities on one site that must not see each other's ledgers, stock or sales | Items, customers and suppliers may be shared across companies, so restrictions need to be tested per DocType |
| Territory | Documents linked to the assigned territory, such as customers and sales transactions tied to a sales region | Sales teams that own a geographic or market area and should only work accounts in it | Territory must be filled consistently on customers and orders, or records without it can disappear from view |
| Branch or warehouse | Documents linked to a warehouse or branch-style field, typically stock and sales transactions | Store, plant or site staff who should only handle stock and orders for their own location | Transactions that span several warehouses may need careful review, and transfers can expose both sides |
| Custom link field | Any link field you choose, such as a project, cost center, department or sales person | Business rules that do not match the standard fields, for example restricting by project or cost center | Requires a link field with clean data and a clear owner, and adds testing before each change |
| Applied to all DocTypes | Every DocType that has a link to the chosen value, based on the permission rule | Broad rules where one dimension, such as company, should govern the whole site | Can hide documents from reports and lists unexpectedly, so confirm how each report behaves before go-live |
| Applied to selected DocTypes | Only the DocTypes you select for the rule | Cases where a manager needs one dimension on sales but not on accounting or HR records | More rules to document and review, and gaps appear if a new DocType is not added to the list |
| Hierarchy-based (manager view) | Employee-linked records of staff who report to the user, when hierarchy permissions are generated | Managers who approve or review work by their direct reports and need matching visibility | Depends on an accurate reports-to hierarchy in Employee records, and a stale hierarchy gives wrong access |
How to set up user permissions for company and territory
This sequence restricts each non-admin user to the companies, territories or branches they own, and it ends with a documented test that proves the restriction holds on lists, reports and link fields. Confirm each stage before moving on, because a gap at one stage shows up as missing data or as data leaking across units.
Map the link fields that carry the restriction
Before creating any rule, list the link fields that point to Company, Territory or Branch on each DocType in scope, such as Sales Order, Sales Invoice, Purchase Order, Stock Entry, Customer and Item. Someone who knows the data model, usually a functional lead with a developer or consultant, should confirm the field names on your version and note which DocTypes have no such field. Done means you have a written table of DocType, link field and whether it is mandatory, which becomes the test plan later.
Define the users and their allowed values
Agree with the business which users may see which companies, territories or branches, and whether any user needs more than one value. Record each user with the values they hold and their roles, and flag users with System Manager or Administrator access, since those accounts are not limited by these rules. Done means a signed-off access matrix exists and the list of exceptions is short and justified.
Create the user permission records
As a System Manager, open each user record and add User Permissions for the allowed Company, Territory or Branch values. Use one record per allowed value, and confirm the Apply To Document Type option is set only where you want the restriction to apply to a single DocType. Done means every non-admin user in the matrix has the expected permission rows, and a quick export or list view of User Permission confirms there are no stray rows.
Apply the permission to each DocType
Check how the restriction takes effect on each DocType in the test plan. Where a link field is defined on the document, the User Permission on that link value filters records for users who hold it. Where you need the restriction to behave differently for one DocType, set the Apply To options explicitly and record the reason. Confirm this on a test site, not in production, and note which DocTypes behave as expected and which need adjustment.
Set up hierarchy-based access for managers
If managers should see records belonging to people reporting to them, use the hierarchy-based option in the ERPNext documentation, which can create User Permissions from the Employee reports-to hierarchy. Check the generated records against the org chart, and confirm that the hierarchy is maintained as people join, move or leave. Done means a sample manager sees exactly their team's records and no others.
Test with a non-admin account
Sign in as a test user from each role in the matrix, not as Administrator. Confirm that list views show only permitted records, that the count matches what you expect from a sample of the data, and that opening a record outside the permission returns no access. Done means each test user's results are written down against the test plan, with pass or fail for each DocType.
Check reports, dashboards and link fields
Run standard reports, such as Sales Analytics, Accounts Receivable or Stock Balance, and confirm that totals reflect only permitted values. Open link field dropdowns on forms and check that they do not offer values outside the user's permission. Search for records by name, since search can expose items that list views hide. Done means the report and search results match the test plan, and any gaps are logged with an owner.
Document the rules and the known gaps
Record the final permission design, the DocTypes covered, the hierarchy rules, and the list of admin and System Manager accounts that bypass these restrictions. Confirm with your security or compliance lead how these accounts are controlled, and schedule a review each time a new DocType, company or territory is added. Done means the document is approved and stored with the configuration backup, and the test plan is repeatable.
How hierarchy-based access works for managers
Hierarchy-based access lets a manager see the documents of employees who report to them, and ERPNext documents this as a user permission option that Frappe HR can generate from the Employee reports-to hierarchy. The result is a set of User Permission records that tie a manager's user account to the employees below them, so the manager's view of linked documents follows the org chart instead of a list maintained by hand. Before you switch this on, confirm that Frappe HR is installed on the same site, that every Employee record has a correct user link, and that the reports-to field is filled in for everyone who should appear in a manager's scope. If an employee has no linked user or no reports-to value, the generated permissions will be incomplete and the gap will look like a permissions bug when it is really a data problem.
Generated permissions do not maintain themselves. When someone changes managers, leaves, or moves to another branch or territory, the reports-to field changes but the existing User Permission records do not automatically reflect every consequence for every DocType, so you need a defined process for regenerating or correcting them. Assign an owner for Employee master data, decide who is notified when a reporting line changes, and check the permissions after each organizational change rather than assuming the old access was removed. Former managers are the usual source of access that outlives the reporting relationship that justified it, so include offboarding and transfers in that process.
Before relying on the hierarchy for access decisions, test it with real accounts. Log in as a sample manager and a sample employee in a test copy of the site, confirm which Sales Orders, Purchase Orders and other linked documents appear, and confirm that a manager cannot see documents outside their reporting line. Also check how the hierarchy interacts with company, territory and branch restrictions you have already configured, since two sets of user permissions on the same DocType can combine in ways that hide data. Confirm the exact behavior for your ERPNext and Frappe HR versions in the hierarchy documentation and in your own environment before you rely on it for a control.
Common mistakes that hide data from the wrong users
User permissions in ERPNext filter what each user sees, and they filter in ways that are easy to misread. The mistakes below usually show up as reports that look short, documents that disappear, or users who report nothing at all. Check each one during testing, before the site goes live to non-admin users.
Empty reports from linked permissions
A user permission on one DocType can empty reports that join records through other link fields. For example, a user restricted to one company may see no Sales Orders in a report that pulls customers from a different company, because the joined rows fall outside their permission. The symptom is a report that returns fewer rows for a restricted user than for an admin. The fix is to map every link field each report touches, then confirm that the restricted user can read every linked master they need.
Missing permissions on child tables and masters
Child-table rows inherit access from their parent document, but linked masters such as Item, Warehouse or Price List do not. A user who can create a Sales Order may get a link error or a blank field when the item or warehouse sits outside their permitted set. Review each transaction DocType for link fields that point to masters, and grant read access to those masters in the same role or user permission set.
Blanket permissions left after a reorganization
A user permission added during a rollout often outlives the structure it described. When a branch closes, a territory is split or a manager changes teams, the old rows keep granting or blocking access to records nobody expects. Schedule a review of user permission rows at each reorganization, and export the list of rows per user so changes are visible before they take effect.
Users with no permission rows
When a DocType has user permission rows for some users, the rule applies to them, but users with no matching rows for a linked field can see nothing that depends on it. A new hire with no branch assigned may open a list and find it empty, which looks like a broken site. Decide in advance whether each user needs at least one row per dimension, and document the default for new accounts.
Confusing role and user permissions
Role permissions decide which DocTypes and actions a role can use, while user permissions limit which linked values a user can see. Teams often try to restrict branch access by editing roles, or grant broad access by adding user permissions, and get the opposite result. The fix is to set role permissions first for what a job function may do, then add user permissions for which company, territory or branch the user may touch.
Testing only with administrator accounts
Administrator and System Manager accounts bypass the checks that restricted users hit, so a test run under them proves little. Create test accounts for each job function and each branch, log in as them, and run the same lists, reports and documents the business will use. Record what each account sees and compare it with the expected set before sign-off.
Questions buyers ask before setting up ERPNext user permissions
Can our own team configure ERPNext user permissions without a partner?
Yes, a team with ERPNext experience can configure user permissions in the desk, since they are set per user on link fields such as Company, Territory and Warehouse. The difficulty lies less in the clicks than in the design: deciding which DocTypes must be filtered, how hierarchy applies, and which standard reports will break when access narrows. Teams without a Frappe developer usually find the first pass manageable and the testing and edge cases harder. Ask your team to list every DocType that carries a restricted link field before deciding who does the work.
What drives the effort of setting up user permissions?
Effort rises with the number of companies, territories or branches, the number of DocTypes that link to them, and the reporting you need across groups. Each additional restriction dimension multiplies the combinations a tester must check. Other drivers include whether managers need hierarchy-based visibility, how many roles already exist, and whether custom DocTypes or scripts must respect the same rules. Ask any provider to break the quote down by these dimensions so you can see what changes if the scope grows.
What do we need to provide before the work starts?
Prepare three inputs: a role matrix showing which job functions need which records, an org chart that shows reporting lines and branch or territory ownership, and test accounts that represent each role on a non-production site. Without the role matrix, permissions tend to be granted by copying existing users, which carries over mistakes. Without test accounts, nobody can verify what a user sees. Agree on who signs off each rule, because access decisions usually belong to finance or operations, not IT.
How long does testing take for user permissions?
Testing time depends on how many role and record combinations must be checked, not on the permission setup itself. A small site with one company and a few roles needs a short pass through the key documents. A multi-company group with territory and branch restrictions needs a test for each role against each restricted document type, including submit, cancel and reports. Ask your provider to list the test cases in the written scope and to state which ones are included in the fixed price and which need your users to validate.
Why do users still see data they should not after we set permissions?
The most common cause is a document type that has no link field to the restricted dimension, so the permission never applies. Another is a user who holds a role with broad read access, which overrides the intent of a narrower permission. Reports and list views can also expose totals or names from linked records. Check the permission rules for each DocType, then run the standard reports as a restricted user, and confirm that aggregated figures do not leak restricted detail.
How does hierarchy-based access work for managers?
ERPNext can create user permissions from the Employee reports-to hierarchy, so a manager sees documents belonging to employees who report to them. This is useful for approvals and team oversight, but it needs a clean Employee record for every person, accurate reporting lines, and a process for updating them when people move. A stale reporting line can grant a manager access to the wrong team or hide records from the right one. Confirm the exact setup steps with the official documentation for your version before you rely on it.
When does a partner add value to user permission work?
A partner adds the most value when the scope spans several companies, custom DocTypes, integrations that write records, or a regulated environment where access decisions need evidence. DeployOpen plans and implements these controls inside your own infrastructure, documents the rules, and prepares test evidence that your internal auditors can review. DeployOpen does not issue audit reports or certifications, so final assessment stays with your independent auditor. Most engagements are fixed-scope, so the written scope should name the companies, roles, DocTypes and test cases covered.
How to test that users see only their own records
Before go-live, prove that restriction works by logging in as real non-admin users, one dedicated account per company, territory or branch, and checking what each one can reach. Do not test with System Manager or Administrator accounts, because those roles bypass most of the rules you are trying to verify. Create at least one test user for each scope, assign only the operational roles that user would really hold (for example, Sales User or Stock User), and attach the matching User Permissions for Company, Territory or Branch. Include one user with no restrictions in a scope you expect to be global, so you can confirm the difference is intentional rather than accidental.
Work through each surface a user touches. Check list views first, then Report Builder and standard reports such as the general ledger, stock balance or sales analytics, since they filter differently from list views. Open print formats and PDFs for documents from another scope. Type into link dropdowns on sales orders, stock entries and journal entries to see whether records outside the user's scope appear as suggestions. Export a list to CSV or Excel and compare the row count with what the screen shows. Finally, open linked documents, such as a delivery note reached from a sales invoice, because a user may be blocked from the main document but still see its neighbours. Record each check in a table with the user, the document or report, the expected result, the actual result and the tester's initials.
Repeat this test suite after every ERPNext or Frappe upgrade, after a new company, territory or branch is added, and after any change to roles or User Permissions. Upgrades can change how reports and link fields apply restrictions, and organizational changes often leave stale assignments behind. Confirm with your implementation partner which reports and custom scripts sit outside the standard checks, since a server script or custom report can bypass permissions unless it is written to respect them. Keep the signed test record with your access review evidence so auditors can see what was tested, by whom and when.
How DeployOpen scopes and delivers ERPNext access control
DeployOpen plans, implements, tests, documents and supports self-hosted ERPNext inside your own infrastructure, including the user permission model that limits each person to their company, territory or branch. Engagements are fixed-scope, with the permission design agreed in writing before any configuration begins.
How we scope
- Map which DocTypes carry company, territory or branch link fields and which ones must stay open.
- Agree written scope covering roles, user permission rules, hierarchy-based manager access and test accounts.
- Confirm with your team who owns each permission decision, including exceptions for group finance and shared records.
How we build
- Configure user permissions per DocType and apply the Apply To All Document Types option only where it fits the design.
- Set up hierarchy-based access for managers, where the reports-to structure drives which employee records they see.
- Test each job function with dedicated accounts, checking lists, reports, linked documents and print formats for leaks.
How we hand over
- Deliver a permission matrix listing each role, DocType, link field and the rule that governs it.
- Document common mistakes that hide data, such as missing default values or overlapping restrictions, with checks your team can repeat.
- Walk administrators through adding a user, changing a branch assignment and reviewing permissions after a reorganization.
How we support
- Offer ongoing support and upgrades as a retainer, so permission rules are reviewed when ERPNext versions change.
- Re-run access tests after new companies, territories or branches are added to the site.
- Confirm with your team how permission changes are requested, approved and logged over time.
