- A buyer sends a supplier a message: “Can you confirm the delivery date?”
- In an email inbox, the supplier now has to reconstruct the context.
- For a procurement marketplace built on Medusa, we created a messaging capability that keeps buyer-supplier conversations inside the commerce context.
- The goal was not to add a generic chat bubble.
The client problem
A buyer sends a supplier a message: “Can you confirm the delivery date?”
In an email inbox, the supplier now has to reconstruct the context. Which property is asking? Which order? Does the sender belong to that property? Has another colleague already replied? If the conversation began from a product page, which product was under discussion?
For a procurement marketplace built on Medusa, we created a messaging capability that keeps buyer-supplier conversations inside the commerce context. A durable thread connects one customer property with one supplier. Product and order cards can travel with the conversation. Access, unread state, live updates and notifications all derive from the same thread.
The goal was not to add a generic chat bubble. It was to make every message answer two questions immediately: who may participate, and what commercial situation are they discussing?
Procurement messages need more context than consumer chat
A consumer support conversation can often begin with an email address and an order number.
Property procurement is more structured. One buyer may act for several properties. One property may have several authorised buyers. A supplier has a team rather than one inbox. The same property can purchase from many suppliers, and the platform's own administrators may need a separate support channel with a vendor.
If messaging ignores those relationships, it creates a second, weaker identity system beside commerce. Users can be invited into the wrong thread, order references are pasted manually and support loses the scope that Medusa already knows.
We modelled conversations around existing business relationships instead. Buyer-vendor communication is anchored by property and seller. Platform support is anchored by seller and admin. The message domain reuses commerce context rather than asking users to rebuild it in prose.
That makes the conversation part of the product, not a detachable communication plugin.
Give each property-supplier relationship one durable thread
For buyer-vendor communication, the platform keeps one active conversation for a given property and seller.
This avoids a new disconnected thread every time somebody opens the message panel. A buyer can return after an order, a quote or a product question and find the continuing relationship with that supplier. The vendor team sees the same history.
A database uniqueness rule protects that identity even if two requests try to create the conversation at the same time. The application first looks for the existing property-seller thread; the database resolves a creation race back to the same record.
Platform-to-vendor support uses a different conversation type, with one active admin-support thread per seller. It is kept separate because a marketplace administrator and a property buyer do not have the same role or visibility.
Two conversation types are enough to express the client's communication boundaries without turning every message into an unstructured ticket.
Derive access from commerce relationships
The storefront does not trust a property ID supplied by the browser on its own.
It resolves which properties belong to the authenticated customer through the property-customer relationship. A buyer can list and open only property-vendor conversations for those properties. When creating a new thread, the requested property must be in that accessible set.
On the vendor side, the authenticated member resolves to a seller. Vendor conversations must belong to that seller. Platform administrators can access admin-vendor support threads, not private property-vendor conversations.
These checks happen when listing conversations, opening a thread and sending a message. A hidden menu or filtered inbox is not the boundary.
The result is easy to explain: the buyer participates because they belong to the property; the vendor participates because they belong to the supplier; the conversation exists between those two business entities.
Attach the product or order instead of describing it again
Free text is a poor way to preserve commerce identity.
“The blue drill” can refer to several variants. “Order 1042” may be mistyped. A screenshot becomes stale and cannot be linked back to the live record.
The message model supports structured product-introduction and order-context cards alongside text. When a buyer starts from a product, the product card can be inserted once into the property-seller thread. When the discussion concerns an order, an order-context card can carry that reference into the conversation.
The system avoids adding the same product or order card repeatedly to the same thread. Later text remains readable without a wall of duplicated context blocks.
This gives the interface a richer starting point. The supplier can see the relevant commerce object before reading “Can you confirm this?”. The conversation does not have to copy every mutable product or order field; it carries a structured reference and presentation payload appropriate to the moment.
Keep text and system context visibly different
A product card was not typed by the buyer. An order card is not a sentence from the supplier.
We store contextual cards as system messages with explicit payload types, while text messages retain their human sender type and identity. That distinction lets the interface render each item correctly and avoids attributing generated context to a person.
The thread can therefore contain:
- a product card introducing what the buyer was viewing;
- an order card identifying the transaction under discussion;
- buyer and vendor text replies;
- timestamps and sender presentation from the relevant actor record.
The message list joins customer, vendor-member or admin identity as appropriate. Participants can see whether a person or the system introduced each piece of information.
Structured context improves usability without pretending that every payload is conversational text.
Track unread state per participant
A single read flag on the conversation cannot serve several people.
When one supplier colleague opens a thread, that should not automatically mean every other colleague read it. A property can have multiple buyers. Platform support has its own actor identity.
The system stores read state per conversation, actor type and actor ID. Sending a message marks the sender's thread as read and increments unread counts for the other side's participants. Opening or explicitly marking the conversation read resets that actor's count and records the time.
The conversation list joins the current actor's read state, so the inbox can show a personal unread count while sharing the underlying thread.
This is a small data model with a meaningful business effect: “unread” describes a person's relationship to the conversation, not a global property that the first viewer can erase for everyone.
Make updates feel live without making live delivery the source of truth
After saving a message, the application publishes targeted events for the relevant seller, property or admin stream. Connected interfaces receive message-created and conversation-updated events through server-sent events, with periodic heartbeats keeping the stream active.
The live event tells the UI to refresh quickly. The database remains the durable conversation history.
That ownership matters. A browser can disconnect. An in-process event can be missed during a restart. A user can return tomorrow. In each case, listing the thread reads the saved messages and per-actor state rather than depending on an event having reached every screen.
We use realtime behaviour to improve responsiveness, not to define whether a message exists.
For a larger multi-instance topology, the event transport could later move behind a shared broker while the same conversation contract remains intact.
Notify people after preserving the message
Not every participant keeps the messaging screen open.
Once a message is stored, the platform resolves recipients, applies buyer or seller notification preferences and can create feed or email notifications with a safe link back to the conversation. The notification identifies the sender and conversation label and includes a bounded preview.
The ordering is deliberate: save the message first, attempt notifications second.
If an email provider is unavailable, the buyer's message should not disappear. The notification failure is logged while the durable conversation remains available in the platform. Feed and email are delivery channels around the message, not competing sources of truth.
The recipient model follows the thread type. A property-vendor message notifies the other participating side; an admin-vendor message follows the platform-support relationship. Preferences decide whether enabled channels are used.
This separates commercial communication from the reliability of any one notification provider.
Turn contextual support into an actionable product trail
The same model also improves support quality.
When a supplier asks the platform team for help, the admin-vendor thread already identifies the seller. When a buyer raises an issue with a supplier, the property-vendor thread identifies both commercial parties. Product and order cards provide a direct clue about the affected object.
An operator no longer starts by asking for the account, property and order number in three follow-up emails. The original conversation carries enough structure to navigate into the relevant product surface.
This does not automatically diagnose the issue or create a complete ticket workflow. It provides a much better hand-off boundary: a durable conversation ID, authorised actors, commercial scope and optional entity context.
Those elements can later feed escalation, service-level tracking or a dedicated support case without losing the customer's original discussion.
Keep message scope honest as teams become more complex
The current vendor conversation boundary is the seller team. It should not be described as more granular than it is.
Elsewhere in the platform, Account Managers can have property portfolios and Store Owners can have stock-location responsibilities. Messaging can eventually apply similar recipient and visibility rules if the business wants private sub-team conversations.
That would be a deliberate extension: resolve the participants from the conversation property, supplier role and current commercial scope, then enforce it consistently on list, detail, send, unread and notification paths.
The important lesson is not to imply that notification targeting alone restricts conversation access. Recipient resolution and data access are separate controls. Both must reflect the intended team model.
By starting with explicit conversation types and server-side actor checks, the platform has a clear place to evolve that policy rather than scattering it through frontend components.
A practical commerce-messaging checklist
Before adding messaging to a Medusa marketplace, ask:
- What durable business relationship defines a conversation?
- Should one property and supplier share one thread or several cases?
- Is platform support a separate conversation type?
- Does the server resolve buyer properties and vendor seller identity?
- Are list, detail and send paths protected by the same boundary?
- Can product and order context be attached structurally?
- Are contextual cards visibly distinct from human messages?
- Are duplicate cards avoided inside one thread?
- Is read state stored per participant?
- Does realtime delivery enhance rather than replace persisted history?
- Is the message saved before notifications are attempted?
- Do email and feed respect channel preferences?
- Can notification failure occur without losing the message?
- Does vendor visibility match the actual team-scope policy?
The useful unit is not “a chat message”. It is an authorised, contextual and recoverable commercial conversation.
Why Medusa was the right foundation
Medusa already knew the customers, sellers, products and orders. The client needed communication to preserve those relationships rather than creating a parallel support universe.
We extended the platform with durable conversation, message and read-state models; storefront, vendor and admin actor boundaries; contextual product and order cards; live events; and preference-aware notifications.
The outcome is simple for users. A buyer can ask a supplier about the thing they are already viewing. The supplier opens the same thread with the property and commerce context attached. Everyone can return later and recover the history.
That is the advantage of building communication inside an extensible commerce architecture: the message begins where the business context already lives.