- A marketplace can onboard many suppliers and still need a different answer for every buying organisation.
- One property group may have approved three regional vendors.
- Showing everybody the same unrestricted assortment pushes policy into training and manual checks.
- For a property-procurement platform built on Medusa, we implemented organisation-level vendor eligibility.
The client problem
A marketplace can onboard many suppliers and still need a different answer for every buying organisation.
One property group may have approved three regional vendors. Another may have negotiated with a national supplier. A third may require insurance and tax documents before any catalogue becomes purchasable. Some vendors can serve the properties but have not been selected by procurement.
Showing everybody the same unrestricted assortment pushes policy into training and manual checks.
For a property-procurement platform built on Medusa, we implemented organisation-level vendor eligibility. An authorised buyer organisation chooses from vendors that can serve it and have passed the required credential review. The resulting allowed set becomes an input to catalogue visibility without copying or forking the marketplace catalogue.
The key was to keep three decisions separate: deliverability, compliance and commercial selection.
A marketplace catalogue is not automatically an approved assortment
Marketplace supply answers what sellers offer. Organisational procurement answers what this company permits its teams to buy.
Those are different questions.
A seller may be valid on the platform but irrelevant to a particular geography. It may deliver locally but still lack documents required by a property organisation. It may have passed compliance while procurement prefers another contracted supplier.
If all three decisions become one “approved vendor” boolean, nobody can explain why a product disappeared or what must happen to restore it.
We modelled them as a sequence:
- Can this seller deliver to the organisation's properties?
- Has this organisation approved the seller's current credentials?
- Has an authorised operator enabled the seller for purchasing?
Only then does the supplier belong to the organisation's allowed set.
Let deliverability define the candidate list
Vendor selection should not offer suppliers that cannot serve the buyer.
Before accepting a set of seller IDs, the platform resolves sellers deliverable for the organisation. A submitted seller outside that set is rejected on the server.
This prevents a misleading administrative experience. Procurement cannot “approve” a supplier whose fulfilment topology does not reach its properties and then discover the problem during checkout.
It also keeps geography in the correct model. Vendor selection does not store a second list of states, cities or postcodes. Delivery profiles and service zones remain responsible for reach. Selection consumes their answer.
When a seller expands its territory, it can become a candidate. When it stops serving the organisation, an old identifier cannot bypass the current deliverability check.
Make compliance a prerequisite, not a side note
For organisations that require vendor credentialing, selection begins only after review.
Supplier documents can include tax forms, insurance, licences or organisation-specific evidence. The platform records current documents and a review status for each organisation-seller relationship.
When an operator submits the enabled vendor set, the backend verifies that every selected seller has an approved review. A missing or pending review cannot be promoted by simply adding the seller ID to the request.
This order matters.
Commercial preference should not overrule compliance. At the same time, compliance approval does not force procurement to use the vendor. It merely makes selection possible.
The platform can therefore explain two different blocked states: “documents are not approved” and “approved, but not enabled by this organisation.”
Keep the organisation's choice as a durable decision
The selection itself has a small but explicit model.
For each organisation and seller, the platform records whether the relationship is enabled, who enabled it and when. The live organisation-seller pair is unique, preventing several competing active records for the same choice.
Updating the assortment replaces the active set. Sellers no longer selected are disabled; retained and newly selected vendors become active with current decision context.
That replacement behaviour matches the administrative question: “Which suppliers are enabled now?” It avoids interpreting a long sequence of add and remove events every time the catalogue needs an answer.
Decision history can still be audited through timestamps and actors, while the resolver receives a clear current set.
Recheck when supplier evidence changes
Approval cannot remain valid forever if the evidence changes underneath it.
When a supplier updates current credential documents, affected organisational reviews return to pending. The access cache for those organisations is invalidated.
This prevents a previous approval from silently covering a materially different document set. Procurement's commercial selection may still exist, but eligibility now reflects that compliance must review the new evidence.
The distinction is valuable: the organisation does not have to rebuild its preferred-vendor list because a certificate was replaced. The same selected relationship can become temporarily ineligible until review completes.
Selection expresses intent. Credential state determines whether that intent is currently actionable.
Resolve one allowed-seller set for catalogue decisions
Downstream catalogue code should not reimplement the policy in every endpoint.
The platform resolves allowed credentialed seller IDs by joining active organisational selections with approved reviews. That set can feed storefront catalogue visibility and search constraints.
This creates one reusable answer to “Which sellers may this organisation buy from?”
The catalogue remains shared. Products are not copied into an organisation-specific database. Instead, the current organisation context narrows the shared marketplace supply through the allowed seller set.
That architecture matters at scale. Forking catalogues creates synchronisation work whenever a seller changes a product, price or image. A visibility rule preserves one product source while supporting distinct purchasing policies.
Add shopping lists and exclusions as separate layers
Vendor selection is only one layer of assortment.
An organisation may also negotiate a shopping list containing specific products. It may exclude individual items even when their supplier is generally allowed. The platform's broader visibility algebra combines these rules rather than pretending one filter can express every policy.
The order of questions stays understandable:
- Is the seller eligible for this organisation?
- Is the product inside the applicable negotiated assortment?
- Has the organisation explicitly excluded it?
- Is it otherwise visible and purchasable in the current commerce context?
This is why the vendor article should not claim to solve all catalogue governance. It supplies a clear supplier-level decision that composes with product-level rules.
Do not rely on the storefront to enforce policy
A hidden product card is not an access control.
The storefront can use the allowed set to present a clean catalogue, but server routes and search must apply the same organisational rule. Otherwise a buyer can reach an excluded supplier through a direct URL, stale search result or handcrafted request.
The project therefore treats the resolved seller set as backend policy input, not only UI state. Cache invalidation follows selection and credential changes so subsequent access resolution does not keep an obsolete answer.
A separate retained article covers parity between REST and Elasticsearch in depth. The important business rule here is simple: organisational eligibility must survive every route into the catalogue.
Why Medusa was the right foundation
Medusa owns products, carts and commerce lifecycle. The marketplace extension adds sellers and fulfilment. We added organisation, property, credential and selection rules around those primitives.
This is exactly why an extensible commerce engine suited the project.
We did not create one storefront per customer or duplicate supplier catalogues. We modelled the client's procurement policy and injected its result into shared commerce discovery.
New rules can remain composable. Delivery answers whether service is possible. Credentialing answers whether evidence is acceptable. Selection answers whether procurement wants the relationship. Product lists and exclusions answer which items are in scope.
Medusa remains the transaction foundation while the platform expresses who is allowed to transact with whom.
What this changed for the client
Each buying organisation could operate inside a curated marketplace without losing the advantages of shared supply.
Procurement could choose its suppliers. Compliance retained authority over current documents. Delivery rules prevented impossible candidates. The storefront could show a relevant assortment, and backend policy could reuse the same allowed seller set.
The visible feature is a vendor-selection screen. The business capability is governed choice.
An organisation can say, “These are the suppliers our teams may use,” and the platform can explain every prerequisite behind that statement.
Walk one supplier through the decision
Consider a regional maintenance supplier joining the marketplace.
Its fulfilment setup covers the cities where Organisation A owns properties, so it appears in that organisation's candidate list. Organisation B operates outside the service territory, so the same supplier is not offered there. No procurement preference has been evaluated yet; this is simply delivery feasibility.
The supplier uploads its current tax and insurance documents. Organisation A requires credentialing, so its compliance team reviews those sources. While the review is pending, the supplier can be inspected but not enabled. Once the review is approved, an authorised procurement operator can include the supplier in the organisation's active selection.
Products from that seller can now participate in Organisation A's catalogue, still subject to negotiated shopping lists, explicit product exclusions, price, stock and normal commerce rules. Organisation B remains unaffected because the marketplace did not change the global seller or product records.
Later, the supplier replaces its insurance certificate. The platform resets the affected review to pending and invalidates the organisation's cached access answer. The commercial selection still records that Organisation A wants the relationship, but the allowed set no longer treats it as currently eligible until compliance approves the new evidence.
This example shows why one boolean would be inadequate. At different moments, the supplier is deliverable, documented, approved, selected and eligible. Those states are related, but they are not interchangeable.
It also shows why the model is valuable beyond the administration screen. The platform can tell operations what action is missing instead of presenting an unexplained empty catalogue: configure delivery, upload evidence, complete review or enable the vendor.
A practical eligibility checklist
Before implementing organisation-specific vendors, define:
- What proves a seller can serve the organisation?
- Is credential approval organisation-specific?
- Can procurement select a seller before compliance approval?
- Who may replace the organisation's enabled set?
- Are actor and decision time recorded?
- What happens when a supplier replaces a credential document?
- Is selection intent preserved while eligibility becomes pending?
- Can downstream services resolve one canonical allowed-seller set?
- How do shopping lists and product exclusions compose with seller eligibility?
- Do storefront, API and search apply the same organisational policy?
These answers turn vendor filtering into a defendable procurement rule.
The broader lesson
The client did not need 200 suppliers to look available to every buyer.
They needed a marketplace where shared supply could be narrowed by real organisational decisions: service coverage, current compliance approval and procurement selection.
We kept those responsibilities separate, then composed them into one allowed seller set for Medusa catalogue access.
The catalogue stays shared. The buying policy becomes personal to the organisation. And every hidden supplier has an explainable reason.