- A buying team chooses a supplier.
- Then the supplier replaces one document.
- If the marketplace simply overwrites a PDF, nobody can prove what was reviewed.
- For a B2B procurement marketplace built on Medusa, we designed supplier credentialing as a versioned eligibility workflow.
The client problem
A buying team chooses a supplier. The supplier uploads a W-9, proof of insurance, a business licence and a tax certificate. Compliance reviews the file. Procurement enables the vendor.
Then the supplier replaces one document.
If the marketplace simply overwrites a PDF, nobody can prove what was reviewed. If it keeps the approval untouched, buyers may continue purchasing on the strength of evidence the reviewer never saw. If procurement preference overrides compliance, the control is cosmetic.
For a B2B procurement marketplace built on Medusa, we designed supplier credentialing as a versioned eligibility workflow. Documents stay private. Replacements preserve history. Organisation reviews identify the exact evidence considered. Any document change reopens review. A supplier becomes eligible only when compliance approval and procurement selection are both true.
The result turns a folder of files into a business rule the catalogue can respect.
The client problem: “preferred supplier” is not the same as “approved supplier”
Procurement and compliance answer different questions.
Procurement asks whether the organisation wants to buy from a vendor: does the assortment fit, is the relationship useful, should this supplier appear in the approved buying set? Compliance asks whether the current evidence satisfies the organisation's requirements.
A marketplace also asks a third question: can this supplier serve the organisation at all? Delivery geography may already exclude the seller before preference or credentials are considered.
Collapsing those decisions into one enabled flag makes the system impossible to explain. A supplier can be commercially attractive but still awaiting review. Another can be compliant but not selected by procurement. A third can be selected and approved but unable to deliver to the buyer's properties.
We preserved those layers and made credentialing responsible for one clear boundary: which current supplier evidence did this organisation approve?
Give the dossier a vocabulary the business recognises
The credential model recognises W-9, proof of insurance, business licence and tax certificate as first-class document types. It also supports an “other” category with a required custom label for organisation-specific evidence.
That vocabulary is simple, but it matters. A list of anonymous attachments forces every reviewer to infer purpose from filenames. Typed documents let the supplier understand what they are providing and let the buyer understand what is present.
Each record retains the original filename, MIME type, size, uploader and upload time. The marketplace can present a useful dossier without exposing the storage implementation.
The model does not try to turn every document into the same form. A tax record and an insurance policy remain files with different business meanings. What the platform standardises is their identity, history and relationship to review.
Keep compliance evidence private by construction
Supplier credentials are not catalogue media.
They can contain tax identifiers, legal addresses, policy information and other details that should never inherit the public visibility of a product image. Uploads therefore enter private file storage rather than a public asset bucket.
Seller identity comes from the authenticated vendor context. The browser does not submit an authoritative seller ID and choose whose dossier to modify. Download paths retrieve the credential record and apply the relevant seller or organisation scope before streaming the private file.
This gives both sides an understandable contract. A supplier sees its own current documents and history. An authorised buying organisation can inspect the evidence for a vendor it is reviewing. Public marketplace visitors cannot enumerate credential URLs.
Privacy is part of the domain model, not a convention that every future screen must remember.
Replace a document without erasing what happened
Business documents change. The wrong response is to overwrite the file in place.
When a supplier re-uploads a current credential, the platform first verifies that the document belongs to the authenticated seller and is still current. It admits the new private file, marks the previous record non-current, timestamps when it was superseded and creates a new current record that points back to the prior document.
The supplier API returns two useful views: the current dossier and the historical sequence. Normal users see what should be reviewed now; support and audit journeys can understand how the evidence changed.
This history also protects meaning. A review from last month can remain linked to the document IDs that existed last month even after the supplier presents a replacement today.
Versioning here is not a filename suffix. It is an explicit relationship between business records.
Snapshot the evidence behind every decision
An approval should answer more than “who clicked approve?”
The organisation's credential review stores the seller, status, reviewer, optional note, submission time, review time and last document-change time. On approval or rejection, it also captures the IDs of the current documents that formed the reviewed dossier.
The route refuses to approve a supplier with no current credential document. That prevents an empty dossier from acquiring a valid-looking green status.
Because document IDs are snapshotted, the review remains interpretable later. The platform can distinguish “this supplier was approved” from “these specific versions were approved”.
That is the level of evidence a B2B workflow needs. People make the substantive compliance decision; the system preserves exactly what they decided against.
Reopen review whenever the evidence changes
The most important transition happens after a new upload or replacement.
The platform finds buying organisations that require credentialing and already have a review or selection relationship with the supplier. For each affected organisation, it resets the review to pending, clears the former reviewer decision, records the new document-change time and invalidates the organisation's access cache.
This prevents a stale approval from silently following a new file. The supplier does not need to remember which buyers reviewed the old dossier, and each buyer does not need to discover the change through email.
The transition is conservative in the right place: changing compliance evidence removes current eligibility until the organisation reviews again.
That creates a durable rule for suppliers too. They can update documents when needed, but the marketplace makes the commercial consequence explicit and predictable.
Let each buying organisation make its own review
Marketplace compliance is not always global.
Different buying organisations can have different vendor programmes, internal policies or reviewer responsibilities. The review is therefore keyed by organisation and seller, not stored as one universal “verified vendor” badge.
One supplier can be approved by one organisation and pending for another. Both reviews reference the supplier's current dossier, but each organisation owns its decision, reviewer note and timing.
This is especially useful in procurement platforms that serve many property operators. The marketplace provides the evidence workflow; it does not pretend that one buyer's approval automatically satisfies every other buyer's governance.
Organisation scope is also applied when returning candidate vendors and credential summaries. Review state is always interpreted in the context of the authenticated buying organisation.
The same supplier record supports multiple relationships without flattening their controls.
Make compliance outrank commercial preference
Procurement still needs the ability to choose which eligible suppliers it wants to use.
The platform stores an organisation-specific vendor selection with enabled state, actor and time. But when credentialing is required, selection alone cannot make the seller purchasable. Eligibility requires an approved credential review and an active selection.
The order matters. Delivery determines whether the supplier can serve the organisation. Compliance determines whether the current evidence is approved. Procurement selection determines whether the organisation wants the supplier in its buying set.
If any required layer fails, the seller remains blocked and the summary exposes a reason such as missing documents, pending review, rejection or not enabled.
This prevents a well-intentioned procurement click from bypassing governance. Commercial choice remains powerful, but it operates inside the compliance boundary.
Carry eligibility into catalogue visibility
A compliance workflow creates value when it changes what buyers can actually do.
The backend resolves the set of approved and enabled seller IDs for an organisation that requires credentialing. Downstream catalogue and search visibility can consume that allowed set alongside delivery and other organisational rules.
The shared product catalogue is not duplicated per customer. Instead, the organisation's request context supplies an eligibility filter. A product from a blocked supplier cannot become visible merely because its title matches the search query.
When a document change reopens review, the access cache is invalidated so later requests resolve the new pending state rather than continuing with the earlier allowed set.
This connects compliance to the buying experience without asking every frontend component to know how W-9s or insurance reviews work. The catalogue receives a business answer: these sellers are currently eligible for this organisation.
Give suppliers and reviewers different operational views
The supplier needs a document workspace. The buying organisation needs a review workspace.
The supplier view separates current documents from history and shows organisation review statuses, notes and timestamps. It tells the vendor which evidence is active and whether a customer organisation is still pending, approved or rejected.
The buyer view lists candidate suppliers with credential summaries, opens the current private documents and records an approval or rejection with a note. The reviewer does not need access to the supplier's general dashboard.
These views use the same underlying records but answer different jobs. The supplier maintains evidence; the organisation judges it; procurement chooses among the resulting eligible sellers.
The separation reduces back-channel coordination. Status is visible in the marketplace rather than reconstructed from an email thread and a shared drive.
Why Medusa was the right foundation
Medusa provided sellers, products, customer authentication and the commerce requests where eligibility ultimately matters. The project extended that foundation with private credential documents, organisation reviews, vendor selections and organisation-aware access resolution.
That architecture kept compliance connected to commerce. The review is not trapped in a standalone document portal while the storefront continues to show every supplier. Its result becomes an input to which products the buyer can discover and purchase.
At the same time, Medusa did not need to become a document interpretation engine. Human reviewers retain the substantive decision. The platform owns privacy, history, workflow state and enforcement.
Choosing an extensible commerce engine let us add the client's supplier-governance model without duplicating the catalogue or replacing standard seller and product primitives.
The supplier-credentialing checklist
Before connecting compliance to purchasing, ask:
- Which document types does the business recognise?
- Can organisation-specific evidence carry a clear custom label?
- Are credential files private by default?
- Is seller ownership derived from authentication?
- Who may download a supplier document?
- Does replacement preserve the prior version?
- Can current and historical dossiers be viewed separately?
- Does a review snapshot the exact document IDs considered?
- Can an empty dossier ever be approved?
- Does any document change reopen affected reviews?
- Are access caches invalidated after that change?
- Is approval scoped to the buying organisation?
- Is procurement selection separate from compliance approval?
- Can selection ever bypass a pending or rejected review?
- Does the catalogue consume the resolved eligible-seller set?
These questions turn document collection into a governed buying capability.
The broader lesson
Supplier compliance is not a folder. It is a state transition with commercial consequences.
For this marketplace, private typed documents form a current dossier with preserved history. Each organisation reviews the exact versions in front of it. Replacing evidence reopens the decision and invalidates cached access. When credentialing is required, only a supplier that is both approved and actively selected becomes eligible.
That makes the workflow easier to explain to every participant. Suppliers know which files are current. Reviewers know what they approved. Procurement can choose vendors without overriding compliance. Buyers see an assortment aligned with their organisation's rules.
The platform does not merely store evidence. It carries the meaning of that evidence all the way to the catalogue.