- A property company does not have one buyer.
- It may have a central owner who needs the full portfolio, a regional manager responsible for several sites, a supervisor running one property, buyers placing orders, colleagues preparing wis
- A standard ecommerce split between “admin” and “customer” cannot express that organisation.
- For a multi-property procurement marketplace built on Medusa, we introduced six business roles: Master, Manager, Supervisor, Buyer, Shopper and Accountant.
The client problem
A property company does not have one buyer.
It may have a central owner who needs the full portfolio, a regional manager responsible for several sites, a supervisor running one property, buyers placing orders, colleagues preparing wishlists and accountants who need invoices but should never enter the shopping journey.
A standard ecommerce split between “admin” and “customer” cannot express that organisation. Giving everyone broad access exposes the wrong properties and actions. Creating a separate commerce account for every building fragments suppliers, reporting and governance.
For a multi-property procurement marketplace built on Medusa, we introduced six business roles: Master, Manager, Supervisor, Buyer, Shopper and Accountant. A role says what a person can do. A property relationship says where they can do it. The backend combines both before it returns orders, approvals, products or finance data.
That distinction let one customer organisation behave like the organisation it represents.
The client problem was responsibility, not login
Authentication answers one question: who is this person?
The client's real questions began after login. Can this person manage the whole portfolio or only three properties? Can they place an order or only prepare a list? If a purchase exceeds a threshold, who should approve it? Can finance review invoices without seeing catalogue and checkout screens? What happens when someone changes region while their browser session is still open?
Those are not navigation preferences. They affect which commercial records the server may expose and which state transitions a user may trigger.
We therefore avoided building permissions as a collection of hidden menu items. The model starts with an organisation membership, assigns one canonical role, and then adds explicit links to properties where the role needs a local perimeter.
The result is a small vocabulary that business teams can understand and engineers can enforce consistently.
Two axes: capability and perimeter
Role-based access is often designed as one long list of permissions. Multi-site procurement needs a second axis.
The capability axis describes actions: administer the organisation, manage properties, browse, build a wishlist, place an order, approve a request or work with accounting. The perimeter axis describes the sites whose data may participate.
A Manager and a Supervisor may both have management capability, but only for properties connected to them with a manage relationship. A Buyer or Shopper may be connected with buy access to the sites they serve. A Master has organisation-level responsibility and does not need to be manually copied onto every property.
This separation avoids two common failures. A role alone is too broad: “buyer” does not say which property the person buys for. A property assignment alone is too vague: it does not say whether the person may browse, order or approve.
Every protected journey needs both answers.
Master: one portfolio view without making everyone an administrator
The Master represents organisation-wide responsibility.
This role can operate across the portfolio and owns organisation administration. It is the natural escalation point when a decision sits above regional or property-level authority.
The important design choice is not to simulate that reach by creating a property link for every existing site. That approach becomes brittle as properties are added and can accidentally turn a missing assignment into lost access. Organisation scope is explicit for the Master.
Equally, global visibility is not inherited by the rest of the team. A Manager, Supervisor or Buyer remains constrained by property relationships even though they belong to the same organisation.
This gives central leadership one coherent view while preserving delegation. The organisation can add a new property without granting it to every local operator, and it can move local responsibility without changing the central account.
The commerce platform mirrors the reporting line rather than flattening it.
Manager and Supervisor: management rights inside assigned properties
Regional and site management needed a middle layer between organisation ownership and purchasing.
Manager and Supervisor are treated as supervisor-like roles for property access: their relevant property links carry the manage level. Membership endpoints check those links before listing or changing subordinate assignments. A Manager or Supervisor cannot use management capability to administer an unrelated property in the same organisation.
The approval workflow can still distinguish the two roles. A request made by a Buyer can move to a Supervisor; a Supervisor's request may move to a Manager; a Manager can escalate to the Master. Configured amount and budget thresholds influence which level is required.
This matters because “manager” is not simply a larger dashboard. It is a place in an operational decision chain.
By grounding that chain in property relationships, the platform can support a regional manager across several sites and a local supervisor at one site without cloning rules or organisations.
Buyer: transact for the sites that assigned them
Buyers are the people who turn a property need into a commercial order.
Their organisation membership gives them the Buyer capability, while property links define the locations they may act for. The active property then becomes part of the request context used by catalogue, order and approval journeys.
This avoids relying on a delivery address typed at checkout as proof of authority. A user cannot gain access to a property's orders merely by knowing its identifier or address. Server-side queries resolve the authenticated customer, organisation and property relationship.
When a purchase needs approval, the request retains property context so the system can find the appropriate management perimeter and escalation level. The Buyer remains able to prepare and submit legitimate work without receiving management access to every other transaction at the site.
The distinction is useful for organisations with central suppliers but decentralised purchasing: one marketplace, many accountable buying perimeters.
Shopper: contribute to purchasing without being allowed to purchase
Some employees know what the property needs but should not place the order.
For them, we created the Shopper role. A Shopper can browse products available to an assigned property, request a product summary and manage wishlists. They can assemble useful purchasing intent without entering checkout or the wider order and finance APIs.
This is enforced in backend middleware. The middleware canonicalises the requested Store path, rejects malformed or unexpected paths, allows a deliberately small set of read and wishlist operations, and verifies the selected property belongs to both the organisation and authenticated user.
That server-side boundary matters. Hiding the cart button would create a nicer interface but no security contract; a direct API request could still reach the forbidden action.
The Shopper turns procurement into a collaborative process. Site staff can identify needs and prepare lists, while an authorised Buyer controls the commercial commitment.
Accountant: finance visibility without a disguised buyer account
Accountants need broad financial context for reasons that have nothing to do with shopping.
The storefront gives this role a finance-focused perimeter: accounting review, funding reports, notifications and relevant settings. The default destination is accounting rather than a catalogue dashboard, and unrelated storefront routes are rejected by route policy.
Backend accounting helpers apply their own role and organisation checks to sensitive operations. The user experience and API boundary therefore work together: the interface shows finance work, and the server protects finance data.
This role also solves a product-design problem. Without it, teams often grant an accountant administrator rights simply because administrators can see invoices. That brings unrelated organisation and purchasing powers along for the ride.
A dedicated role expresses the actual job: review and prepare financial information across the permitted organisational context, not administer or buy on behalf of the company.
A role is never the only server-side check
The word supervisor on a session is not enough to authorise a property operation.
Protected routes resolve organisation context and, where relevant, active property context. Property-level approval access queries manage relationships. Shopper middleware verifies assignment. Order queries intersect role semantics with linked properties. Finance routes distinguish organisation-wide roles from property-bound callers.
This layered approach handles a subtle but important case: a valid user with a valid role asking for a valid resource in the wrong property. All three objects may exist, yet the request must still fail.
The browser uses the same role vocabulary to remove inaccessible journeys and choose sensible default pages. But frontend routing is a usability layer, not the authority. Sessions can be stale, URLs can be typed and clients can call APIs directly.
The backend remains the final decision-maker for data and mutations.
Normalise historical roles before they spread
Role models evolve. This repository contained a historical admin value that needed to coexist with the newer vocabulary.
Instead of teaching every route two meanings, a shared role utility normalises admin to Supervisor. It also parses only known role values, identifies supervisor-like roles and maps organisation roles to manage or buy property access.
That small canonicalisation layer prevents drift. One feature does not interpret admin as Master while another interprets it as Buyer. New routes consume the same definitions rather than maintaining local arrays with slightly different semantics.
There is a business benefit as well: changing the product's vocabulary does not instantly strand existing members. Compatibility is handled at the boundary while the internal model stays coherent.
Permissions become easier to explain because the system has one language for them.
Make approval routing follow the organisation
Purchase approval is where a role model proves whether it represents reality.
The workflow considers the requester role, purchase amount, configured thresholds and available approvers. A Buyer normally escalates to Supervisor. Supervisor responsibility can escalate to Manager, and Manager responsibility can escalate to Master. The property relationship helps locate eligible local approvers rather than notifying every manager in the organisation.
Budget overage can also influence routing. That means responsibility is connected to the commercial decision, not only to a static page permission.
The platform retains the decision level with the request so approval screens, notifications and history can explain who was expected to act. An absent local approver can be handled as an explicit routing condition instead of silently approving or abandoning the purchase.
This is the point of modelling roles as domain concepts: they shape the transaction, not merely the interface around it.
Design role changes for an existing session
Permissions can change while a user is logged in. A colleague may be moved to another property, changed from Buyer to Shopper or given an Accountant role.
The interface must re-evaluate accessible routes from current role data and redirect users away from a page that no longer belongs to their perimeter. More importantly, the next backend request must resolve the current organisation and property relationships again rather than trusting an old navigation state.
This is why server-side checks sit close to the route or shared domain helper. Removing a menu item only affects the next render. Removing an assignment must affect the next data request.
The safe product behaviour is also the clearest: the user lands in the journey appropriate to the new responsibility and receives a controlled denial if an old tab tries to continue a forbidden action.
Access changes become operational events, not reasons to recreate the account.
Why Medusa was the right foundation
Medusa supplied customer authentication, commerce APIs, carts and orders. It did not automatically know this client's organisation chart, property estate or approval hierarchy—and it did not need to.
Its extensibility let us add organisation membership, property relationships, request context, specialised middleware and approval workflows around the commerce engine. Standard purchasing primitives remained useful while the platform gained the client's operating model.
On a less extensible system, teams often encode this structure in tags, duplicate stores or a growing collection of app-specific exceptions. The complexity still exists; it is simply pushed into less reliable places.
Choosing Medusa was therefore an architecture decision tied to the business problem. We knew the platform could be extended so one account could support central oversight, regional management, local buying, collaborative lists and finance operations without pretending those users were identical.
The technology choice created room for the organisation to remain itself.
The role-design checklist
Before implementing multi-site procurement roles, ask:
- Which responsibilities exist above the property level?
- Which roles manage sites, and which only buy for them?
- Can one person be responsible for several properties?
- Which users may prepare demand without placing an order?
- Does finance need organisation-wide visibility without buying capability?
- Is property access represented by an explicit relationship?
- Does that relationship distinguish management from purchasing?
- Are organisation and property checked on every sensitive route?
- Can a URL or client-supplied property ID widen access?
- Does approval routing follow property responsibility?
- What happens when the expected local approver is missing?
- Are historical role values normalised centrally?
- Does the frontend hide irrelevant journeys?
- Does the backend still reject them directly?
- What happens to an open browser session after a role change?
These questions turn an access matrix into a usable operating model.
The broader lesson
B2B roles should describe the client's work, not the software's menu.
For this procurement marketplace, six roles cover distinct responsibilities. Master provides portfolio leadership. Manager and Supervisor manage assigned properties and participate in escalation. Buyer transacts for assigned sites. Shopper contributes product intent through catalogue and lists. Accountant works inside a finance perimeter.
Role capability is always combined with organisation and property scope before protected data or actions are exposed.
That is what allows many people to share one commercial platform without sharing one set of powers. The ecommerce engine remains common; the operating perimeter changes with the person and the property.
When the roles match the business, governance stops feeling like friction. It becomes the way the platform helps the organisation buy together.