A customer portal is a restricted area of a web application where logged-in users interact with their own data, documents, orders or applications. Unlike a public-facing website, a portal authenticates every visitor, shows only information tied to their account and enforces rules about what they can view, edit or submit.

Building one means making decisions across several layers at once: how users prove who they are, what they are allowed to do, which data surfaces for each person, how documents move between states, and what happens when something goes wrong. These decisions sit between business operations and technical implementation, which is why they need input from both sides before any code is written.

Portal decisions to settle before delivery

Core building blocks

Every customer portal rests on the same set of functional components, even if the business context differs:

  • Authentication and session management — how users log in, how sessions are created and expired, and whether additional factors such as two-factor authentication are required.
  • Role-based access control — which user types exist, what each type can see and do, and whether permissions need to vary per account rather than just per role.
  • Data presentation — the information pulled from backend systems and displayed to the user, such as order history, account balances or application status.
  • Document handling — uploading, downloading, versioning and approving documents within the portal.
  • Messaging and notifications — in-portal communication between the customer and the business, plus alerts sent by email or other channels when specific events occur.
  • Payment and billing interactions — viewing invoices, making payments, managing subscriptions or setting up direct debits, depending on the business model.
  • Integration points — connections to existing CRM systems, accounting software, payment gateways or other internal tools that hold the source data.

The portal itself rarely holds the authoritative record. It reads from and writes to systems that already exist in the business. Understanding where the real data lives, and who owns the logic that governs it, is essential before scoping the build.

Control of portal data, accounts and future change

Who owns the source code, where it is hosted and who holds the credentials for infrastructure and third-party services are questions that should be settled in the contract, not discovered later. If the business does not own the code or cannot access the deployment environment, switching suppliers or making independent changes becomes difficult or impossible. These points are covered in detail in the guide to source code ownership, but the principle applies directly here: a portal is a long-lived business asset, and the business should retain control over it.

Defining the use cases clearly

Portals fail when the business tries to serve every possible user need in the first release. The practical starting point is to list what specific actions a customer needs to perform, grouped by user type. For example:

  • A wholesale buyer needs to view product catalogues, place orders, download invoices and track deliveries.
  • A regulated-services client needs to submit applications, upload supporting documents, view assessment progress and receive decision notifications.
  • A tenant in a property portfolio needs to view lease details, log maintenance requests and see resolution status.

Each of these implies different data structures, different workflows and different integration requirements. Writing them out as concrete sequences — "the user does X, the system does Y, the user sees Z" — forces clarity before estimates are produced.

Roles and permissions

Most portals need at least two or three distinct roles. A basic structure might include:

  • End customer — can view and edit their own data, submit requests and download their own documents.
  • Account administrator — can manage other users within the same customer organisation, assign permissions and view aggregated reporting.
  • Internal staff — can view records across customer accounts, process submissions and manage configurations.

The complexity increases when permissions need to vary not just by role but by account. One customer organisation might be allowed to self-serve on billing, while another requires staff intervention. These rules should be documented as part of the specification, not left for developers to interpret. The role-based access control guide covers this in a step-by-step format.

Document workflows

If the portal handles documents, the business needs to define what happens at each stage. A typical document workflow includes submission, validation, review, approval or rejection, and archival. Questions to answer before building:

  • What file formats are accepted, and are there size limits?
  • Does the system need to validate document contents automatically, or is manual review sufficient?
  • Can a customer replace a submitted document before review, or must they request a withdrawal?
  • How are version histories stored and displayed?
  • What are the retention and deletion rules, and do they need to align with a specific regulatory framework?

These decisions affect database design, storage costs and the complexity of the user interface. Leaving them vague produces a portal that works for happy-path testing but breaks under real operating conditions.

Messaging and notifications

In-portal messaging allows customers and staff to communicate within the context of a specific record — an order, an application or a support request. This is more structured than email because the conversation is tied to the relevant data and visible to authorised users on both sides.

Notifications are separate from messaging. They are alerts triggered by events: an application status changes, a document is approved, a payment is received. The business needs to specify which events trigger notifications, who receives them and through which channels. Over-notifying leads to users ignoring alerts; under-notifying means customers repeatedly log in to check for updates. The notifications planning guide sets out a method for getting this balance right.

Payment and billing interactions

If the portal includes payment functionality, the business must decide whether to build payment processing directly or integrate with an existing billing platform. Direct integration with a payment gateway gives more control but shifts responsibility for PCI-DSS compliance and card-data handling onto the project. Using a hosted payment page or a billing service such as Stripe, GoCardless or a dedicated subscription platform reduces compliance scope but introduces a dependency on that service's features and uptime.

Either way, the portal needs a clear model for what the customer sees: current charges, payment history, downloadable invoices, upcoming renewal dates and any options to change plan or cancel. These requirements should be specified in terms of data sources — which system generates the invoice, where is it stored, how does the portal retrieve it — rather than just describing the desired screen layout.

Integration with existing systems

A customer portal that does not connect to the business's existing software is usually a standalone database that creates more work, not less. The key integration points typically include:

  • CRM or customer database — the source of truth for customer details, contact information and relationship history.
  • Accounting or billing system — the source of invoices, payment records and credit notes.
  • Operational systems — order management, case management or specialist software that holds the transactional data the customer needs to see.

Each integration has a cost in development time, ongoing maintenance and potential failure points. The business should prioritise integrations by operational impact and phase non-essential connections into later releases. The integration estimation guide explains how to assess this work realistically.

Over-scoping the first release

A frequent failure is attempting to replicate every function currently handled by email, phone calls and spreadsheets in a single build. This inflates the estimate, extends the timeline and increases the chance that the delivered portal does not match actual user behaviour because no real customers have used it yet. A practical approach is to identify the single highest-frequency interaction — the one that generates the most support queries or manual processing — and build the portal around that. Additional features follow based on observed usage, not assumed requirements.

Skipping process mapping

Building a portal without first mapping the underlying business processes leads to software that automates a broken workflow rather than improving it. If the current process involves three email exchanges, a phone call and a manual spreadsheet update, the portal should replace that sequence with a clear digital flow — not simply digitise each step in isolation. The process mapping guide describes how to do this before engaging a development team.

Weak authentication and session handling

Portals hold customer data, and in many cases sensitive commercial or personal information. Authentication should use industry-standard methods — hashed and salted password storage, secure session tokens with sensible expiry, and the option for two-factor authentication. Session management should log users out after a period of inactivity and invalidate sessions on the server side when a user explicitly logs out. These are not optional extras; they are baseline requirements for any system that exposes customer data. Security specifics should be reviewed by a specialist as part of the project, since best practices change over time.

Ignoring mobile usage

Customers will access the portal from phones and tablets regardless of whether the business planned for it. A portal built only for desktop screens creates a poor experience that drives users back to phone and email. Responsive design is a minimum expectation. Whether a separate mobile application is justified depends on usage patterns and is a separate decision covered in the guide to when to add mobile apps.

No clear acceptance criteria

Without written acceptance criteria, the business and the development team will have different definitions of "done." Each feature in the portal should have a set of testable statements that describe the expected behaviour, including edge cases. For example: "When a customer uploads a document larger than the permitted size, the system displays an error message stating the maximum allowed size and does not create a partial record." The acceptance criteria guide explains how to structure these so that both sides can agree on what constitutes a complete delivery.

Data migration treated as an afterthought

If the portal replaces an existing system or a collection of spreadsheets, the business needs a plan for moving historical data into the new structure. This includes deciding which data is worth migrating, how it will be transformed to fit the new schema, how it will be validated after import and what the rollback plan is if the migration produces errors. The data migration planning guide sets out this process step by step.

Checks before committing to the portal build

  • Can you list the three to five most important actions a customer will perform in the portal, in order of frequency?
  • Have you mapped the current process for each of those actions, including the people, systems and handoffs involved?
  • Do you know which system holds the authoritative data for each piece of information the portal will display?
  • Have you defined the user roles and what each role is permitted to do, including any per-account variations?
  • Is there a written set of acceptance criteria for the first release, covering both normal behaviour and error states?
  • Have you confirmed who will own the source code, where it will be hosted and who will hold administrative access after launch?
  • Is there a support arrangement that covers bug fixes, security patches and infrastructure monitoring after go-live?
  • Have you planned what happens if you need to change suppliers — can you get the code, the data and the access credentials without the current provider's cooperation?

Answering these questions does not guarantee a smooth build, but failing to answer them makes problems significantly more likely. A customer portal is an operational system, not a marketing asset, and the standards for clarity, control and risk management should reflect that.