How the ERPNext customer portal gives customers self-service access
Customers keep emailing for order status and invoice copies, and your team keeps answering them by hand. The ERPNext customer portal lets customers log in to check orders, invoices and shipments and raise issues, so routine status questions stop passing through your sales or support inbox. Access is granted per person, not per company, which is the first design decision to make. The mechanism uses a Website User with the Customer role. That website user must be linked to a Contact, and the Contact must be tied to the Customer record and listed in that Customer's Portal Users table. Only documents that belong to that customer, and that the portal role is allowed to read, appear to the logged-in person. Your team should confirm this against a test customer before any live invitation goes out, because the visible set depends on how the Contact and Portal Users links were set up.
Sharing PDFs by email still makes sense for one-off documents sent to a customer who will never return, or for a small account where a few messages a year cost little. A portal earns its setup effort when many customers repeatedly ask the same questions, when several people at one customer need separate visibility, or when disputed invoices and open issues need a shared record instead of a thread of forwarded messages. Ask your implementation partner to walk through which customer groups fit each route, and to confirm with a written scope how onboarding, Contact maintenance and user offboarding will be handled. Access reviews are the part teams most often skip. Contacts change jobs, and a former employee who remains in a Portal Users table keeps a view of that customer's orders and invoices until someone removes the link. Plan a recurring review of portal Contacts alongside your normal account maintenance, and record who approves new portal users so the access model stays auditable.
How Website Users, Contacts and Portal Users connect
A customer sees data in the ERPNext portal only when three links line up: a Website User with the Customer role, a Contact that holds that user's email, and a Contact linked to the Customer whose Portal Users table lists the same user. The customer documentation describes this chain, and it is the first thing to verify when a customer reports an empty portal. Each link is separate. A Website User with the right role but no Contact link has no customer record to attach to, so the portal shows nothing. A Contact linked to the Customer but missing from the Portal Users table is the most common gap, because the Contact can look correct on screen while still giving no access. Confirm the exact field names, the Portal Users child table layout and the screen paths in your running version before you write a test plan, since these labels have changed between releases.
A single Contact can relate to more than one Customer, which matters for buyers who share an accounts-payable mailbox across subsidiaries or for resellers who order for several end customers. Each Customer then has its own Portal Users entry, so you control which records each login can see by adding or removing rows per Customer rather than by creating duplicate contacts. Decide early whether a person should see all related customers or only one, and test with a user linked to two customers to confirm that orders, invoices and issues from the wrong customer stay hidden. Ask your partner to document the provisioning steps, because user onboarding and offboarding will repeat for every new account and every departed employee at a customer.
Which portal setup fits which customer relationship
A business customer often has several people who need to see orders, invoices and shipments, such as a procurement lead, an accounts payable clerk and a site manager. In ERPNext, each of these people is a Contact linked to the same Customer, and each person who should log in needs a Website User with the Customer role. The Contact is then added to the Customer's Portal Users table, which is what gives that login access to the Customer's documents. Each Contact should carry only the people your customer has authorized, because every linked Contact can see the Customer's records in the portal.
- Linking pattern: one Customer record, many Contacts, and only the Contacts listed in Portal Users can reach portal pages for that Customer.
- Maintenance owner: the customer's account owner on your side usually approves additions, while a named back-office role updates the Portal Users table when staff change.
- Offboarding: remove the Contact from Portal Users and disable the Website User when a buyer leaves, since access does not end on its own.
- Shared mailboxes: avoid a single shared login for several buyers, because you lose the ability to tie issues and actions to a named person.
- Confirm: which contacts are authorized to raise issues versus only view invoices, and whether the customer wants one approver for new logins.
Before go-live, check with the customer which buyers should see all orders and which should see only their own, and test that the portal shows the correct records for two different Contacts.
Small customers often have one person who places orders, pays invoices and reports problems. The setup is simpler: one Customer, one Contact, and one Website User with the Customer role, added to the Customer's Portal Users table. The main risk here is not complexity but continuity, because the entire relationship depends on one login and one email address. If that person leaves the customer, the account can become unreachable or, worse, still active under a former employee's address.
- Linking pattern: one Customer, one Contact, one Website User, and one entry in Portal Users.
- Maintenance owner: usually the sales or customer success contact who manages the account, with a reminder to review the login when the customer reports a staff change.
- Email ownership: confirm the address on the Contact belongs to the customer's business, not a personal mailbox that could change hands.
- Fallback path: agree how the customer will raise issues if the portal login is unavailable, such as a named support email, so the relationship is not blocked.
- Confirm: whether the customer actually wants a portal login or prefers email, since a portal the customer never uses adds upkeep without value.
Ask the customer to name a second person who can be added later, even if they are not given access today, so that a future handover does not start from scratch.
Some organizations are both customers and suppliers, or act as resellers and partners who buy, sell and need visibility into shared transactions. These relationships raise the stakes on permissions, because a contact that is linked for customer documents may also be the person who handles purchasing, and a portal user should not gain access to supplier-side records by accident. The team should decide which of the customer's people get the Customer role, whether any need a different role for supplier-facing features, and whether the same person should hold both identities in ERPNext.
- Separate identities: keep the customer portal login and any supplier or partner access as distinct decisions, reviewed against each role's permissions.
- Maintenance owner: a named administrator who understands both the sales and purchasing sides, since changes affect both directions.
- Role review: check that the roles granted do not expose internal fields, cost data or documents you do not intend to share.
- Dual-party records: confirm how intercompany or reseller transactions appear to each party before the portal is opened to them.
- Confirm: which ERPNext roles, sharing rules and permission settings apply to each access type, tested with a sample user for each.
Because this model combines several permission sets, treat the first access review as a formal sign-off step, and repeat it whenever a new relationship type is added.
Configuration options and when each one fits
This table compares the main portal setup choices in ERPNext: how website users are created, how contacts link to customers, how Portal Users rows are maintained, which documents customers can see, and how permissions are inherited. Read each row against your customer base, since a choice that suits a small account team may not suit a large customer population with several buyers per company.
| Option | What it controls | When it fits | Trade-off |
|---|---|---|---|
| Website User with Customer role | Login account that lets a customer sign in to the portal and see customer-scoped documents | Each customer buyer who needs their own login and history | Every login is a user to maintain, offboard and review |
| Contact linked to the Customer | Ties a person's email to a Customer record so portal access follows that account | Customers with named buyers, finance contacts or service contacts | Contacts that are not updated when people leave can keep old access |
| Portal Users table on the Customer | Lists which contacts on a Customer can see its portal documents | Customers with several legitimate viewers, such as a purchasing team and an accounts payable team | Rows must be added or removed by hand, so drift is common without a review step |
| Customer-visible orders and invoices | Sales Orders and Sales Invoices shown to linked portal users | Customers who want to check status and pay or download invoices without emailing staff | Visibility depends on the document being submitted and linked to the right customer |
| Shipments and delivery status | Delivery Notes shown with tracking details where recorded | Customers who ask often where goods are | Only useful if dispatch staff record shipments consistently in ERPNext |
| Issues raised from the portal | Issue records created by customers and visible to them | Teams that already run a support process inside ERPNext | Customers see only what support staff choose to share, so internal notes need a clear policy |
| Reliance on standard roles and permissions | Access checks that apply the existing user permissions and roles on linked documents | Organizations that already maintain clean role and user permission rules | Permission gaps in internal roles can carry into the portal, so test each customer type before launch |
How to set up the customer portal step by step
This sequence takes a customer from a version check to a tested portal account, so that each customer sees only their own orders, invoices, shipments and issues. Each step ends with a check you can record before moving on.
Confirm version and enable website access
Confirm which ERPNext version you run and check that it is on the supported list, because the portal depends on your release line and its maintenance status. Then confirm that website features are enabled for your site and that the portal pages load from a browser. Your administrator should record the version number and the site URL in the implementation log. The step is done when a test visitor can reach the portal login page without errors.
Create website users for customer contacts
Create a Website User for each person who needs portal access, using an email address that the customer controls. Keep the account separate from internal System Users, since portal accounts should never receive desk permissions. Ask the customer which contacts should have access, rather than creating accounts for every contact on file. The step is done when each Website User exists, is enabled, and has a unique email address.
Assign the customer role to website users
Add the Customer role to each Website User so that the account is recognized as a customer login rather than a general website visitor. Review the role list on each account and remove any additional roles that were added by default or by a previous template. Your administrator should keep a short list of which accounts hold the role. The step is done when a role review of every portal account shows only the roles you intended.
Link contacts to customers and fill portal users
Open the Contact for each Website User and link it to the correct Customer record. Then add the Contact's email to the Portal Users table on that Customer, so that ERPNext knows which logins may view that customer's documents. Check for contacts that are linked to more than one customer, because those links decide what a user can see. The step is done when each portal user appears in the Portal Users table of exactly the customers they represent.
Test with a sample customer account
Create a test customer and a test Website User, link them as in the previous steps, and log in as that user in a private browser session. Confirm that the portal shows the test customer's sales orders, invoices, shipments and issues, and nothing belonging to other customers. Use records that contain realistic structure but no real customer data, and label them as test records. The step is done when the test account sees only its own documents and the result is written up for sign-off.
Review what each document type exposes
Review the portal view for each document type you intend to share, including orders, invoices, delivery notes and issues. Check which fields and attachments appear, and whether any internal notes, margins or cost details are visible through the portal. Confirm the permission rules that apply to each document type with your ERPNext administrator, and ask the customer to confirm the scope they need. The step is done when a written list of exposed documents and fields is approved by your business owner and security reviewer.
Document the access model and hand over
Record the final access model: which roles apply, how Contacts link to Customers, who approves new portal users, and how access is removed when a contact leaves the customer. Share the procedure with the team that will onboard and offboard customer users. Ask whether your version and any custom scripts need re-testing after upgrades, and confirm who owns that check. The step is done when the runbook is stored with your other ERPNext operating documents and the first live customer login has been verified.
Permission checks and security risks to address before launch
A customer portal exposes ERPNext data to people outside your company, so the risks sit at the boundary between Customer records, contacts and document permissions. The cards below cover the places where access tends to drift, and the controls to verify in your own environment before any customer logs in.
Over-broad sharing of Customer records
Customer-linked documents are only visible to portal users when the permission model and the link between Contact and Customer say so. Review which DocTypes a portal user can reach, and confirm that sharing one customer's record does not expose sibling customers, shared addresses or group-level reports. Test with accounts from at least two customers, and check that a customer cannot change a record by guessing a document name in the URL.
Stale Portal Users lists
The Portal Users table on a Customer's contact decides who can see that customer's data, and nothing removes a person from it automatically when they leave the customer organization. Assign an owner for each customer account, tie removal to offboarding requests, and review the list on a fixed schedule. Ask who receives the notice when a customer's contact changes role.
Internal notes and pricing on documents
Sales orders, invoices and delivery notes carry fields that customers should not see, such as internal remarks, cost-based margins, price list tiers and supplier references. Audit which fields appear in the portal views and print formats, and remove or restrict anything internal. Check comments and attachments too, because they are easy to overlook in a document review.
Account takeover and login policy
Portal accounts are website users, so their security depends on password rules, two-factor authentication and session handling set for the site. Confirm which login policies apply to website users, decide whether customers can use single sign-on through a Social Login Key or an external identity provider, and plan how locked accounts and password resets are handled. Ask your identity team to review the reset flow for account takeover.
Server Script limits for custom portal logic
Custom access rules or portal behavior built with Server Scripts depend on the site allowing them. From version 15, Server Scripts are disabled by default and must be enabled with the server_script_enabled setting, and Frappe Cloud public shared benches do not allow them. Confirm the hosting model before design starts, and move logic that must always run into a reviewed custom app if the platform cannot support it.
Questions buyers ask before opening the portal to customers
How much effort does a customer portal setup take in ERPNext?
The effort depends mainly on how many customers need access, how many contacts sit under each customer, and which document types the portal must show. A small group of customers with one contact each is a bounded configuration task. Each additional contact needs a Website User, a Customer role decision and a row in the Portal Users table, so the work grows with the contact list rather than the customer count alone. Every document type you expose, such as orders, invoices, shipments or issues, adds a permission check to test. Ask the partner to break the estimate down by customer segment, contact volume and document type so you can see which driver moves the number.
What does our team need to provide before the build starts?
The build needs decisions from your team more than it needs technical access. You will need a current list of customers and the contacts who should log in, a view on which customer groups see which documents, and a named owner who signs off the role model before any customer receives an invitation. Your finance team should confirm how invoices and payment status should appear to customers, and your support lead should confirm how issues are raised and triaged. Plan for review meetings where these decisions are recorded in writing, because unclear ownership of these answers is the most common cause of rework.
Can an in-house administrator set up the customer portal alone?
An in-house administrator who already knows ERPNext roles and permissions can configure a simple portal, especially for a small customer base with a narrow set of documents. The harder parts are testing what each Website User can actually see, handling contacts linked to several customers, and keeping the Customer role consistent with your permission rules. Check whether your administrator has time to test with real accounts before go-live, and whether someone else can review the permission settings. A partner is most useful when the portal exposes sensitive financial data or when the access model must be documented for an audit.
How is ongoing maintenance of Portal Users handled?
Portal access changes over time as customers add staff, leave, or change companies, so maintenance is a recurring task. Each change means updating the contact, confirming the link to the right Customer, and adjusting the Portal Users table on that Customer. Decide who can request these changes, how quickly leavers are removed, and how often you review active website users against your customer master. Ask whether the partner will provide a written procedure and a review checklist, and whether that work is covered by a retainer or billed per change. Recurring review effort rises with customer turnover, so estimate it from your expected changes per month.
Which permission checks should we test before customers log in?
Test that each Website User sees only the Customer records linked to their own contact, and that no internal document, draft or unrelated order appears. Check each document type you expose, because access is set per DocType, and confirm that changing a contact or Portal Users row takes effect on the next login. Include negative tests with a user from another customer and with a contact linked to two customers. Ask the partner to document the test cases, the accounts used, and the results, so your security or compliance team can review them. These tests are an input to your own review, not an audit opinion.
What should we ask a partner to include in a fixed-scope quote?
Ask for the exact list of customer segments, document types and contact groups in scope, and for each to be listed as a deliverable. The quote should name the roles and permission rules to be configured, the test cases and accounts used for verification, and who signs off each stage. Ask what is one-time, such as configuration and testing, and what recurs, such as Portal Users maintenance, access reviews and upgrades of the ERPNext version you run. Confirm which items are excluded, such as custom portal pages, integrations with other systems, or migration of existing customer logins, and what triggers a change request.
Does the portal need a supported ERPNext version and a Frappe support plan?
Yes, the version you run matters for how long the portal configuration stays supported. Check the Frappe supported versions page for the current status of your ERPNext and Frappe Framework release before you commit to a design. Frappe's policy also says that warranty coverage from Frappe requires being on a listed version and subscribed to a matching Frappe Cloud support plan, so confirm whether that applies to your hosting. Ask the partner how they will handle the upgrade path for the portal configuration, since permission behavior should be retested after each major version change.
How to test the portal before customers see it
Test the portal with internal accounts that mirror each customer type before any customer receives a login. Create one Website User per test persona, each with the Customer role set on a Contact that is linked to the correct Customer and listed in that Contact's Portal Users table. Cover the types you actually sell to: a direct buyer, a buyer with several contacts under one Customer, a customer whose orders are placed by a reseller, and a contact with no Portal Users entry as a negative control. Confirm the Customer Portal setup and the Customer role's behavior against the ERPNext customer portal documentation for the version you run, because visibility rules can differ between releases.
The core check is isolation. Log in as each test user and confirm that orders, invoices, shipments and issues belonging to other Customers never appear, including through the list views, search, direct document URLs and print formats. Repeat with a contact that belongs to a different Customer to make sure the Portal Users link alone decides access. Then walk through issue creation: raise an issue as the test customer, confirm it is tied to the right Customer and Contact, reply from the internal desk, and confirm the customer sees the reply and nothing else. Record any leak as a blocker and retest after the fix.
Keep evidence that an internal reviewer can follow later. Record the test matrix (persona, Customer, Contact, expected and observed visibility), screenshots or exported lists for each check, the ERPNext and app versions tested, and the names of the people who signed off. Ask your implementation partner to show how this evidence is stored. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. If your portal supports regulated data, ask your independent auditor which evidence format and sample size they expect before the test run begins.
How DeployOpen scopes and delivers the ERPNext customer portal
DeployOpen plans, implements, customizes, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For the ERPNext customer portal, we start by agreeing which customers, documents and actions are exposed, then build the website user, contact and permission model around that decision and test it before any customer logs in.
How we scope
- Inventory which customers, contacts and companies will receive portal access, and who approves each new account.
- Define the documents customers may view, such as orders, invoices, shipments and issues, and the ones that stay internal.
- Agree in writing which permission checks, customizations and integrations are in the fixed scope and which are excluded.
How we build
- Configure Website Users with the Customer role, linked to Contacts and listed in each Customer's Portal Users table.
- Review role and user permissions so a customer can open only their own records, and test that with sample accounts.
- Document any custom fields, scripts or apps, and confirm they are enabled on your version before go-live.
How we hand over
- Provide a written runbook covering account creation, onboarding steps for new customers and offboarding for departed contacts.
- Walk your support and sales staff through how issues raised in the portal reach your queues and who responds.
- Hand over permission test results and a list of open items, so your team can repeat the checks after upgrades.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped separately from the initial build.
- Re-run permission checks after each ERPNext minor release, since both supported major versions receive frequent updates.
- Confirm with your team which portal changes need a new scope and which fall within an existing retainer.
