- An ordinary online shop can treat a customer as a person with an email address and a delivery address.
- The customer may be a company, a homeowners’ association or a property manager.
- Put all of them inside one flat customer account and the platform immediately loses the answer to three basic questions:
- That was the client problem behind one of the most important extensions we built on Medusa for a multi-vendor procurement platform.
The client problem
An ordinary online shop can treat a customer as a person with an email address and a delivery address.
A property business cannot.
The customer may be a company, a homeowners’ association or a property manager. It may operate one site or a large portfolio. One employee needs a view across the entire organisation. Another manages five properties. A local buyer should order only for the building they serve. An accountant needs financial visibility without a shopping journey.
Put all of them inside one flat customer account and the platform immediately loses the answer to three basic questions:
- who is buying?
- for which property?
- under whose authority?
That was the client problem behind one of the most important extensions we built on Medusa for a multi-vendor procurement platform.
Medusa gave us the commerce engine: customers, products, carts, orders, regions and the foundations required to build a modern purchasing experience. What it could not know automatically was how this client’s property business actually operated.
We modelled that operating reality explicitly: organisation, property and unit; then people, roles and property assignments; then an active-property context that the rest of the commerce journey could understand.
The result was not a cosmetic account switcher. It was a shared business language for procurement.
The real customer was an organisation, not a login
The first decision was to stop equating “customer” with “buyer organisation.”
A login identifies a human. An organisation represents the entity that owns the commercial relationship: a company, an HOA, a property-management group or another operating structure. Those concepts overlap in a small retail account, but they diverge quickly in B2B procurement.
If the organisation lives only in a few customer metadata fields, every new feature has to reinterpret those fields. Budgets invent one definition of a site. Orders invent another. Delivery rules look at an address string. Reporting groups purchases by a name that may have changed. Integration code tries to infer which external entity a cart belongs to.
We gave the organisation its own identity, lifecycle and contact information. A person could belong to it without becoming the organisation itself.
That distinction sounds abstract until somebody leaves the company. The organisation must keep its properties, orders, budgets and integrations. Only the departing person’s access should disappear. A durable organisation record makes that behaviour natural.
A property is more than a shipping address
The next trap was to represent every site as an address book entry.
An address answers where a parcel goes. A property answers what operational place the purchase serves.
For this platform, a property carries its own identity, name, type, status, unit count and structured geography. It belongs to an organisation. It can also carry identifiers used to reconcile the same site with external property-management or accounting systems.
That identity matters throughout procurement.
The site can influence which products are visible, which suppliers serve the area, which stock location can fulfil an order, which delivery options make sense, which budget applies and where the eventual expense should be reported. Two properties may share a postal address format while having completely different commercial and operational rules.
We therefore made property a first-class record instead of a decorated delivery address.
The delivery address can change. The business identity of the property remains stable.
Units preserve the final level of operational meaning
Property procurement often needs one more level.
A site may contain several buildings. A building may contain many units. A maintenance purchase can be made for the whole property, a particular building or a particular apartment. That detail matters when the operator later asks where a product was installed, which unit incurred a cost or how a recurring purchase should be attributed.
We introduced explicit unit records below each property. A unit preserves its number, optional building and floorplan information, its own address details when they differ from the parent site, and external identifiers used by connected systems.
We deliberately did not force every order to pretend that it belonged to a unit. Some purchases serve a shared area or the entire site. The hierarchy provides precision when the business process needs it without making the lowest level mandatory everywhere.
This creates a useful model:
Organisation → Property → Unit
Building information sits with the unit data because that matched the source structure we had to integrate. The important architectural lesson is not that every property platform needs the same tables. It is that the commerce model should preserve the operational levels the client uses to make, approve and reconcile purchases.
One organisation still needs several views of the truth
Once the estate existed in the platform, the next client question was obvious: who should see which part of it?
A central owner may need an organisation-wide view. A manager may be responsible for several properties. A supervisor may run a smaller perimeter. Buyers and shoppers may work only for assigned sites. Accounting may operate across the organisation without participating in product selection.
We modelled six buyer-side responsibilities: Master, Manager, Supervisor, Buyer, Shopper and Accountant.
The detailed permission matrix belongs in its own article, because each role has a distinct product journey. The important point for the organisation model is that a role and a site perimeter are separate dimensions.
“Buyer” explains the kind of work somebody performs.
“Properties A, B and C” explains where that authority applies.
Combining those two dimensions allowed one organisation to remain one customer while still reflecting how responsibility was distributed in the real company.
Property assignments turn the hierarchy into an operating model
The relationship between a person and a property is not merely a tag. It carries an access level.
Managers and supervisors can receive management responsibility for specific properties. Buyers and shoppers can receive buying access for the sites they serve. The Master role can see across the organisation without being manually attached to every property one by one.
The assignment rules also respect delegation.
A manager responsible for five sites can assign a buyer inside those five sites. They cannot quietly extend that buyer to a sixth property outside their own perimeter. When somebody changes responsibility, the platform updates the person-to-property links rather than relying on a note in an administrator’s spreadsheet.
This is where the model becomes useful to the business. Central leadership keeps a consolidated account. Regional or portfolio managers work across their sites. Local teams get a focused experience. The company does not need to create a separate commerce tenant for every building, and it does not need to give every employee global access.
Selecting a property changes the meaning of the journey
After login, most users choose the property they are working for.
That selection is easy to mistake for a navigation preference, like choosing a store from a dropdown. In this platform it is a business input.
The request carries an active property identifier. The backend resolves it into a structured context: the property, its organisation, its country and region, and the geographic information required by later decisions.
Now a product request can mean “show me what this property can actually buy,” not simply “show me the catalogue.” A supplier lookup can consider the site being served. A wishlist can belong to the working context of a property. A delivery calculation has a stable destination identity. An order can preserve the organisation and site that gave the purchase its meaning.
The user experiences one simple action—selecting the property—but the platform gains a consistent answer that many capabilities can reuse.
The active property cannot be trusted on appearance alone
Any browser can send a property identifier. That does not mean the signed-in person is entitled to use it.
The platform resolves the selected property, checks that it belongs to the person’s organisation and, on the protected journeys, verifies the member-to-property assignment. A Shopper, for example, can browse products and manage lists for an assigned property but cannot turn that limited role into a broader purchasing or administrative account by crafting a different request.
This is an important distinction for a business audience.
The property selector makes the experience understandable. Server-side membership checks make the context authoritative.
Both are necessary. Without the selector, users cannot navigate a large portfolio comfortably. Without the backend checks, the selector is only a promise made by the interface.
Large portfolios need import, not repetitive onboarding
The model also had to work when the customer estate was too large to enter property by property.
The platform includes controlled organisation-import workflows and staging records for bulk onboarding. Properties and units can arrive with the external identifiers that already exist in the customer’s operational systems. The platform can then maintain those records through dedicated property and unit routes as the estate evolves.
This matters because onboarding is not a one-time data migration.
Properties open, close or change status. Units are added. External systems use their own identifiers. Employees move between portfolios. A useful B2B account model must survive those changes without recreating the organisation or breaking the history attached to it.
By separating durable organisation identity from evolving property and membership records, we gave the customer an account structure that could grow with its operations.
Why Medusa was the right architectural choice
We did not need to rebuild commerce to represent a property business.
Medusa already gave us the core transactional foundations. Its extensibility let us add the client-specific organisational model close to the commerce capabilities that consume it.
The organisation extends the customer relationship. Properties add the operational destination. Units preserve finer attribution. Membership links add human responsibility. Property context connects that structure to catalogue, cart, fulfilment and order journeys.
That is the architectural value of choosing an extensible commerce engine.
The platform does not force the client to simplify their business until it fits a generic account model. The architecture preserves the proven commerce core and adds the concepts required to make it serve the client’s real operation.
For a property manager, that difference is substantial. The question is no longer “Can employees place orders online?” It becomes “Can the platform understand who is buying, for which part of the estate, under which responsibility?”
What this model unlocked
Once organisation and property became shared platform concepts, later business capabilities no longer had to invent their own version of the customer.
- Catalogue and supplier discovery could begin from the site being served.
- Delivery and fulfilment could use property geography instead of an arbitrary account address.
- Collaborative lists could be prepared for a property rather than trapped inside one person’s session.
- Budgets and approvals could follow the organisation and site responsible for the spend.
- Orders could retain the operating context needed for reporting and reconciliation.
- External systems could recognise the organisation, property and unit through durable identifiers.
Each capability still needs its own rules. The hierarchy does not magically implement budgets, permissions or ERP integration. It gives those features a common foundation, so they agree on the entities they are talking about.
That agreement is what prevents a complex procurement product from becoming a collection of disconnected workflows.
A practical modelling checklist
Before extending a commerce platform for a multi-site buyer, answer these questions in business language.
- What is the durable customer entity: a person, a company, an HOA or a property-management organisation?
- Which operational sites belong to that entity?
- Does the business need buildings or units below each site?
- Which external identifiers must survive integration and reconciliation?
- Which roles act globally, and which operate only inside assigned properties?
- Can a manager delegate access only within their own perimeter?
- What does selecting an active property change in the buying journey?
- Which backend checks prove that the selected property belongs to the member?
- How will hundreds of properties and units be onboarded and updated?
- Which later capabilities need the same organisation and property context?
If those answers live only in interface copy or metadata conventions, every new feature will reinterpret them. If they live in the domain model and access paths, the platform can build on them consistently.
The broader lesson
The hardest part of B2B commerce is rarely displaying products in a grid.
It is representing the customer’s business precisely enough that the platform can make useful decisions.
In this project, the client was not one buyer. It was an organisation operating an estate through people with different responsibilities. Medusa did not provide that property-management model automatically—and it did not need to. It provided a strong commerce foundation that we could extend.
We added the missing business language: organisations, properties, units, roles, assignments and an active-site context.
That let the commerce journey start from the client’s real question:
Who is buying, for which property, and under whose authority?
Once the platform can answer that consistently, far more sophisticated procurement becomes possible.