From a business problem to an implementation
From a request for a customer portal to workable scope, a real integration and a measurable business result.
What the portal should change
“We need a customer portal” is a proposed solution, not a development brief. An online shop might want fewer delivery-status calls, easier repeat orders or shared documents. Pick one outcome first: it determines which workflow to build, which data must be trustworthy and what would make the project worth its cost.
Suppose a shop receives 2000 orders each month and 600 questions about status. At four minutes per question, that is 40 hours of support work. Even removing half saves roughly 20 hours a month in this category. The calculation helps compare cost with potential value; it does not prove customers will stop calling.
Portal logins are not enough to measure the result. Someone can open the page, fail to find an answer and call anyway. We need a metric tied to the original problem: status questions per 100 orders and the support time they take.
Shape Up separates the problem from the requested feature and sets an appetite before detailed design. For this portal, agree how much support effort the change could save and how much development that saving justifies.
Follow an order through the business
Follow a real order with a customer, support agent and operations team. Where does the status originate? Who updates it? Why does support know more than the customer? If the answer lives in a private warehouse conversation, a new screen will not make the information accurate.
Include partial shipment, cancellation, returns and carrier delays. For each event identify the source of truth, update delay and person who can correct a mistake. The first useful change may be internal status management, with the portal following later.
A simple map is enough to hold the shared context: step, participant, data and trouble spot. We do not need a book of documentation. We need the business and engineering team to agree on what actually happens between payment and delivery.
Shape Up’s breadboarding technique maps places, user actions and connections before visual detail. For our order-status flow, sketch the order page, status lookup and support handoff; then check which source supplies each answer.
Write the rules for an order
"Update the status quickly" leaves incompatible interpretations. In this example, agree that the portal reflects an accounting-system change within two minutes. If updates stop for ten minutes, it shows the last update time rather than implying current information.
Specify access and transitions. Customers see their own orders; support access follows a work role; changing an email does not automatically transfer another person's history. Define permitted states and who may change them. These rules shape data and validation more than button placement.
An acceptance example contains the starting state, action and expected outcome. A cancelled order must not return to "processing" when an old event arrives again. That example exposes the need to handle event order before implementation begins.
Choose how statuses arrive
Polling an API may be adequate for a small workload. Webhooks can reduce delay, but require handling repeats and missing deliveries. Direct database access may be unavailable or couple the portal to another system's private schema.
A queue can help us survive recipient downtime, smooth a burst or retry processing independently. Once we add it, we also need rules: where the current status lives, how we detect stuck work and what the UI shows before processing finishes. These decisions are part of the feature, not cleanup for later.
Polling every minute does not guarantee an update within a minute. The upstream API can be slow or a run can be missed. We need a time budget, a changes cursor and continuation after failure. The choice is assessed across the full path, not just by its configured interval.
Ship one working integration
The most useful first slice often starts with the integration. We take one order category from the source system to the portal, then test an update, a duplicate and a failure. Ten finished screens will not rescue a broken data path. The interface can be simple at this point, but the data must take the real route.
Plan gradual access, disabling the feature and helping customers during failure. Stale data is a visible application state, not only a log entry. Include people who operate the process in acceptance; they know which apparently minor exceptions stop daily work.
The first slice uses real formats and access. Mock JSON helps build a screen but does not check API quotas, pagination or missing records. If production-like access is unavailable, we record that the integration risk remains. A successful mock demonstration cannot establish readiness of the external path.
Measure support work after launch
Measure status questions per 100 orders, support effort and the share of portal users who still call. Comparing raw call counts can mislead when order volume, season or promotions change.
Where possible, we roll out to comparable groups. Otherwise we record other changes and talk to customers. The portal may pass every test while call volume stays the same. Then we investigate what is missing: accuracy, detail or a trusted way to get help. Shipping closes tickets; the business impact is checked afterwards.
- Choose one order category and record its status questions per 100 orders before launch. Keep the calculation separate from a forecast of future savings.
- Name the status owner, permitted transitions and freshness promise. Write what customers see when the source is unavailable or an update is delayed.
- Deliver one real order from the source system to the portal. Exercise an update, duplicate event, cancellation and missing record before adding secondary screens.
- Give support a way to see data age and report mismatches. Define who fixes them and how the feature can be disabled during trouble.
- Review a complete order cycle after rollout. If calls do not fall, ask which question the portal failed to answer rather than counting logins as success.
Keep reading
How to define MVP scope without building too much
How to build a first release that tests the idea: scope, manual work and essential quality in a job-management service.
Scaling services: when more instances do not help
Why a service can be slow with idle CPU, how extra instances overload the database and what to check before autoscaling.