- An order can be “confirmed” in the commerce platform while the supplier has not yet opened it.
- It can be opened by a vendor employee without being accepted by the supplier's order-management system.
- If all of those moments collapse into one status, the buyer receives false reassurance.
- That was the client problem on a multi-vendor procurement marketplace built with Medusa.
The client problem
An order can be “confirmed” in the commerce platform while the supplier has not yet opened it.
It can be opened by a vendor employee without being accepted by the supplier's order-management system. It can be acknowledged and still be only partly fulfilable. Later, some units may be shipped while the remainder cannot be supplied.
If all of those moments collapse into one status, the buyer receives false reassurance. Operations cannot tell whether the supplier is unaware of the order, reviewing it, refusing it or preparing only part of it.
That was the client problem on a multi-vendor procurement marketplace built with Medusa. We modelled three separate signals: a genuine vendor view, an explicit seller acknowledgement or refusal, and fulfilment against specific SKUs and quantities. When the seller cannot fulfil the remainder, a controlled order edit brings the order back to what can actually be supplied.
The result is not more status labels. It is a clearer answer to the buyer's question: what commitment has the supplier really made?
“Order created” describes the marketplace, not the supplier
The first event belongs to the commerce platform.
Checkout completes, the marketplace creates the seller's order and the vendor dashboard can display it. Notifications may be emitted. None of that proves a human or external supplier system has processed the order.
Many B2B platforms accidentally present internal creation as supplier acceptance. The buyer sees a success screen and assumes the goods are moving. When nothing happens, support has to discover whether the notification failed, the vendor never logged in or the vendor rejected the purchase elsewhere.
We kept order creation as its own fact. It says the marketplace has recorded the transaction and assigned it to the seller. The subsequent vendor signals add meaning without rewriting that original event.
This distinction is especially important in a marketplace. The platform can guarantee its own state transition. It cannot manufacture a supplier commitment.
Record a real vendor view, not a background fetch
A “seen” marker sounds trivial until automated actors start touching the order.
An administrator may open the vendor interface for support. A loader may prefetch data. A monitoring request may call the detail endpoint. If any read marks the order as seen, the buyer-facing signal becomes meaningless.
The vendor dashboard waits until the order detail is actually visible in the document. It then calls a dedicated seen endpoint. That endpoint verifies access to the order and resolves the authenticated vendor identity.
Known marketplace administrator identities are explicitly excluded. An administrator inspecting the order on behalf of support receives the existing value but does not mark the seller as having seen it.
The write is monotonic. It changes the metadata key to boolean true only when it is not already true. The vendor detail and list routes expose the derived seen field consistently.
The signal therefore has a narrow, useful meaning: an authenticated, non-admin vendor user displayed the order detail. It does not mean accepted, packed or shipped.
Protect the seen state from generic metadata edits
Order metadata is often editable through broad administrative routes. That flexibility can undermine a lifecycle signal.
If a caller can submit vendor_has_been_seen: false, the order can become unseen again. If a generic metadata replacement clears the object, a legitimate view disappears. A support tool could also set the value to true without the vendor ever opening the page.
We treat the seen key as owned by the vendor-view workflow. Middleware rejects attempts to write it through generic metadata updates. It also prevents clearing all metadata when an already-seen order would lose the marker.
The server recognises only the boolean value true; a string containing “true” is not accepted as equivalent.
This is a small domain-ownership rule with a large trust effect. When the interface displays “seen”, the value comes from the specific event designed to establish it, not from whichever API happened to update metadata last.
Acknowledgement is a supplier decision
Opening an order still does not tell the buyer whether the supplier accepts it.
The marketplace exposes a separate authenticated acknowledgement endpoint for the seller's external order-management flow. The supplier submits the marketplace order identifier, its own order identifier and exactly one of two timestamps: acknowledged or refused.
The request can also include notes and the property identifier known by the supplier. The platform verifies that the authenticated seller owns the order before storing the acknowledgement under its own metadata key.
The payload rule is explicit: acknowledged and refused cannot both be set, and one of them must be present.
This gives the marketplace a meaningful commercial transition. Acknowledged says the supplier system has recognised and accepted the order into its process. Refused says it has declined. The supplier's own order number creates a shared reference for later support.
Neither outcome is inferred from somebody opening a web page.
Merge independent signals without overwriting them
Seen state and acknowledgement may arrive at almost the same time.
A vendor employee can open the order while an external system posts an acknowledgement. If each path reads the complete metadata object, modifies its local copy and writes the whole object back, the last writer can erase the other signal.
The acknowledgement update merges only the seller_acknowledgment key into the current PostgreSQL JSON. The seen route merges only vendor_has_been_seen. Both use the database's existing metadata value as the starting point.
The corresponding test specifically protects this behaviour: an acknowledgement must preserve concurrent seen state.
This is the right granularity of concurrency contract. We are not claiming that every order operation is globally atomic. We are ensuring that two independent operational facts do not destroy one another simply because they share a metadata column.
Fulfil the order lines that actually exist
Acknowledgement does not guarantee that every ordered unit can be shipped at once.
A supplier integration may report fulfilment using SKUs, while Medusa's fulfilment workflow requires order line-item identifiers. Trusting a browser or webhook to submit arbitrary line IDs would let the caller target data it did not derive from the order.
The SKU fulfilment route loads the order's actual items and resolves each submitted SKU against them. It supports the supplier-facing SKU form used by the integration, including a defined vendor suffix normalisation.
The resolver rejects three ambiguous cases before the Medusa workflow runs:
- a submitted SKU is not present on the order;
- the same canonical SKU appears twice in the request;
- one SKU matches more than one order line.
Only an unambiguous match becomes { line item id, quantity } for Medusa's fulfilment workflow.
The supplier can therefore speak its SKU vocabulary, while the platform retains authority over which order line is actually being fulfilled.
Quantity is a first-class commitment
The route does not turn “SKU found” into “whole line shipped.”
Each submitted item carries a quantity. Medusa's core fulfilment workflow validates that quantity against the order's fulfilment state. This allows the supplier to create fulfilment for the units it is handling rather than forcing an all-or-nothing line assumption.
That matters in procurement. A buyer may order ten units and the supplier may initially fulfil six. The truthful state is not “unfulfilled” and not “completely shipped.” It is six fulfilled, four remaining.
The buyer order presentation derives fulfilment state from the underlying order and shipping graph. The system can show progress without interpreting acknowledgement as physical movement.
We do not use this flow to claim warehouse scanning or carrier delivery confirmation. It records commerce fulfilment for selected order quantities. Shipment labels and tracking belong to their own later operations.
Keeping those meanings separate makes every status more credible.
Cancel only what the supplier cannot fulfil
Sometimes the remaining units will never ship.
Cancelling the whole order would erase the valid part of the transaction. Leaving the full quantity in place would make totals and buyer expectations disagree with reality.
The vendor can invoke a dedicated cancel-remaining-items workflow. It verifies seller ownership and the order's eligible state, then calculates each line where fulfilled quantity is lower than ordered quantity.
For those lines, an order edit reduces the ordered quantity to the fulfilled quantity. A line with zero fulfilled units is effectively removed; a partially fulfilled line remains at the quantity actually supplied. The edit is requested and confirmed through Medusa's order-edit primitives, and a domain event records the operation.
Because the order total changes, a paid order may require a refund for the difference through the appropriate financial flow. The cancellation route does not pretend that adjusting quantity automatically completes every payment consequence.
The important business result is that fulfilled history remains intact while unsupplied remainder is removed explicitly.
Give buyers a progression they can understand
These signals form a simple operational sequence, even though they come from different systems.
Created means the marketplace recorded the seller order.
Seen means a real vendor user displayed it.
Acknowledged means the supplier's process accepted it and supplied its own reference. Refused means the supplier declined it.
Partially fulfilled or fulfilled describes the quantities entered into Medusa's fulfilment lifecycle.
Remaining items cancelled means the order was edited to reflect what the supplier can no longer provide.
Not every order needs every step. An automated supplier may acknowledge before a person opens the dashboard. A manual supplier may view the order first. The value comes from preserving what each event proves rather than forcing one artificial status machine over every vendor.
For support, the same distinctions answer where the order is stuck and who can act next.
Why Medusa was the right foundation
Medusa supplied the order, line-item, fulfilment and order-edit foundations. The marketplace needed supplier-specific commitments around them.
We added seller ownership checks, vendor-view semantics, external acknowledgement metadata and SKU-to-line resolution. We then used Medusa's fulfilment workflow for actual quantities and its order-edit workflow when the remainder had to be removed.
That is the architectural value of an extensible commerce engine. We did not have to replace the order model to support B2B supplier operations. We could add the client's real coordination signals and still rely on established transaction primitives for fulfilment and quantity changes.
The platform becomes more expressive without inventing a parallel order system.
A practical seller-order checklist
Before exposing supplier progress to buyers, define these contracts:
- What does marketplace order creation prove?
- What user action is sufficient to mark the order seen?
- Can administrators or prefetch requests create false seen signals?
- Is seen state monotonic and protected from generic metadata edits?
- What distinguishes viewing from acknowledgement?
- Can the supplier explicitly refuse the order?
- Which external supplier reference should be stored?
- How do concurrent seen and acknowledgement writes preserve both facts?
- Does fulfilment resolve submitted SKUs against the actual order?
- What happens when a SKU is missing, duplicated or ambiguous?
- Are fulfilment quantities validated by the commerce workflow?
- Can partial fulfilment remain visible without closing the entire order?
- How are permanently unfulfilled quantities removed?
- What payment or refund work follows a reduced order total?
- Which signal is visible to the buyer and actionable by support?
If these meanings are vague, status creates reassurance without evidence. If they are explicit, the order page becomes a coordination tool.
The broader lesson
The client did not need a single green badge saying “supplier notified.”
They needed to know what the supplier had actually done.
We separated order creation, genuine vendor visibility, supplier acknowledgement or refusal and quantity-specific fulfilment. Independent metadata updates preserve one another. SKU input is resolved against real order lines. Partial supply remains partial, and the unfulfilled remainder can be removed without discarding fulfilled history.
For buyers, that creates honest progress. For suppliers, it supports both dashboard work and external order systems. For marketplace operations, it identifies the next responsible party.
An order status is useful only when everybody agrees on what it proves.