- A buyer adds products from three suppliers to one marketplace cart.
- The total is comfortably above the free-shipping message they remember seeing.
- That is not necessarily an inconsistency.
- For a B2B marketplace built on Medusa, we implemented free-shipping qualification per seller.
The client problem
A buyer adds products from three suppliers to one marketplace cart.
The total is comfortably above the free-shipping message they remember seeing. Yet one supplier still charges for delivery. Another is free. A third says the buyer needs a little more.
That is not necessarily an inconsistency. In a multi-vendor marketplace, each supplier owns a different commercial promise. One may offer free shipping from $100, another from $300, and another may not offer a threshold at all. The marketplace total cannot decide whether any individual supplier should pay for delivery.
For a B2B marketplace built on Medusa, we implemented free-shipping qualification per seller. The supplier configures one optional minimum. The platform groups cart value by seller, not by warehouse and not by whole cart. Shipping options become free only for the qualifying seller, while the storefront explains the threshold and remaining amount.
The important part is not the zero. It is keeping the same promise from product discovery through checkout pricing.
The client problem: one cart contains several delivery contracts
A marketplace cart looks unified to the buyer, but fulfilment is not.
Products belong to different sellers. Each seller may ship from one or several stock locations. Delivery zones and prices vary by destination. One supplier may absorb shipping after a commercial minimum; another may always charge the carrier rate.
If the platform uses the whole cart total, spending with Supplier A can accidentally unlock free shipping from Supplier B. That is commercially wrong. If it uses each warehouse group, one supplier's basket can be split into several locations and fail a threshold that the supplier intended to apply to the complete order value.
The client needed a rule that buyers could understand:
Add enough products from this supplier, and this supplier's shipping becomes free.
That sentence identifies the correct unit of calculation: the seller subtotal.
Let each supplier own the threshold
The threshold lives in the supplier's preferences, not in a global marketplace constant.
An authenticated supplier Admin can enter a positive minimum through the Vendor application. Leaving the field blank disables the rule. The API validates the value and updates only the preference record belonging to that seller.
The interface says exactly what the number means: the minimum value of this vendor's items required for free shipping. It also states that suppliers qualify separately in a multi-vendor cart and that pickup is unaffected.
In the evidenced implementation, the setting is expressed in USD. That is an explicit product rule, not a hidden assumption. A future multi-currency version would need to decide whether the threshold is stored per currency, converted at evaluation time or attached to market-specific seller policy. The baseline does not pretend that conversion exists.
Giving the supplier control matters. The marketplace provides a capability; the seller chooses the commercial commitment.
Calculate the subtotal before splitting fulfilment
The platform resolves every cart line to its seller through the product-seller relationship.
For each seller, it adds the quantity multiplied by the current unit price across all relevant lines. That produces one subtotal per supplier.
Only after that does the fulfilment plan organise items into seller-and-location groups.
The order of those operations is deliberate. Imagine a buyer orders products worth $120 from one supplier with a $100 threshold. Inventory availability means half the products ship from Warehouse East and half from Warehouse West. If each warehouse independently sees $60, both groups would charge shipping even though the buyer fulfilled the supplier's stated condition.
By calculating $120 at the seller level, the rule survives the internal fulfilment split. Every shipping option for that seller receives the same qualification result.
The warehouse determines how the products travel. The seller subtotal determines whether the supplier absorbs the cost.
Keep every seller independent in a mixed cart
Now consider a cart with two suppliers.
The buyer spends $120 with Supplier A and $80 with Supplier B. Both have a $100 minimum.
Supplier A qualifies. Its shipping options can be priced at zero. Supplier B remains below the threshold and keeps its normal delivery price. The cart total of $200 does not combine the two promises.
That behaviour is essential for marketplace trust. Suppliers can configure a threshold based on their own economics without subsidising products sold by somebody else. Buyers can see which part of the cart needs attention rather than receiving a vague marketplace-wide answer.
The implementation loads the relevant seller preferences in one operation, calculates a map of seller subtotals, then applies the matching minimum only to options belonging to that seller.
There is no accidental cross-seller subsidy.
Change only delivery options, never pickup
Free-shipping policy applies to shipping fulfilment.
The option decorator checks whether an option belongs to a shipping fulfilment set. If it is a pickup option, the function returns it unchanged.
That boundary prevents a commercial message from corrupting a different fulfilment mode. Pickup may already be free, may carry a service fee, or may follow another rule. The shipping threshold has no authority to rewrite it.
For a qualifying delivery option, both the visible amount and the calculated-price amount become zero. For a non-qualifying option, the original price is retained.
In both cases, the response can include three useful facts:
- the seller's free-shipping minimum;
- whether the current seller subtotal qualifies;
- how much more value is required.
The frontend does not need to reverse-engineer the business rule from a zero price. The backend explains the decision it made.
Treat the exact threshold as qualified
Boundary behaviour must be explicit.
If the minimum is $100 and the seller subtotal is exactly $100, the buyer qualifies. The comparison is greater than or equal, not strictly greater than.
Below the minimum, the remaining value is the minimum minus the current seller subtotal. At or above it, the remaining value is zero.
These details sound small, but they prevent frustrating interface contradictions. A buyer should never be told “$0 more for free shipping” while still seeing a charge. Nor should they need to add one cent after reaching the published minimum.
Unit tests pin the exact-boundary decision, seller aggregation and pickup preservation. The rule is therefore executable rather than left to copywriting interpretation.
Show the promise before the buyer reaches checkout
The marketplace also exposes free-delivery eligibility on product discovery surfaces.
This is more difficult than attaching a “free shipping available” badge to every product from a participating seller. The product must be visible to the active buyer, have a live price, be available at a stock location that serves the selected property, and have an applicable shipping option.
The eligibility endpoint performs those checks in the buyer's current property context. It can identify an already-free shipping option or return the seller's configured minimum and whether one unit of the product currently reaches it.
Product cards, comparison views, product detail, recommendations and carousels can consume that response.
The badge is therefore connected to a plausible delivery path. It does not promise free delivery to a location the seller cannot serve.
For a thresholded offer, the message can say “Free delivery from $100” rather than incorrectly claiming that this single item always ships for free.
Recalculate from the live cart at checkout
Discovery is guidance. Checkout is the commercial decision.
A product card usually evaluates one unit. By checkout, quantities may have changed, other products from the seller may have been added, prices may be contextual and fulfilment may use different locations.
The cart fulfilment plan therefore recalculates seller subtotals from the actual lines and applies the threshold to the currently priced delivery options. It does not trust an earlier badge or browser-side flag.
That separation keeps the experience both helpful and correct:
- discovery explains that a supplier offers a threshold;
- the cart shows progress toward the supplier's minimum;
- checkout prices the real delivery options from current state;
- the resulting order receives the chosen shipping economics.
The frontend communicates the rule. The backend remains the authority.
Preserve the original shipping price below the threshold
A threshold is an override, not a second shipping calculator.
Medusa first resolves the delivery option and its calculated price from the cart, region, address, customer and fulfilment context. The marketplace logic then asks whether the seller subtotal qualifies.
If it does, the delivery amount becomes zero. If it does not, the original calculated amount remains untouched.
This matters because a seller can have several delivery options or location-specific prices. The free-shipping rule does not need to understand how each carrier rate was produced. It only decides whether the supplier's commercial promise supersedes that price for this basket.
Keeping those responsibilities separate makes the feature easier to reason about: normal shipping determines the price; the seller minimum can waive it.
Verify the journey through order creation
We verify the journey at several levels.
Unit tests cover normalisation, subtotal aggregation, exact qualification and the pickup boundary. Storefront tests cover the badge and checkout presentation.
An end-to-end dev matrix goes further. It creates isolated suppliers, properties, stock locations, delivery options, products and carts. It defines below-threshold, exact-boundary and above-threshold scenarios. It includes one supplier fulfilling through several stores and carts containing more than one supplier. It then completes the cart and reads shipping totals from the resulting orders.
The value of that matrix is its shape. It tests the commercial promise at the durable boundary rather than stopping when an API response contains free_shipping_qualified: true.
An available test is not itself a claim about every deployment run. It does show what the release proof must cover whenever this capability changes.
A practical free-shipping checklist
Before adding a delivery threshold to a marketplace, ask:
- Who owns the promise: marketplace, seller, location or shipping option?
- In which currency is the minimum defined?
- Can the seller disable it explicitly?
- Are cart lines reliably mapped to sellers?
- Is qualification calculated per seller rather than whole cart?
- Does one seller subtotal span several fulfilment locations?
- Are pickup options excluded?
- Is the exact threshold qualified?
- Does the API return both qualification and remaining value?
- Does discovery verify property coverage, stock and a shipping path?
- Does checkout recalculate from the live cart?
- Is the original priced option preserved below the threshold?
- Do mixed-seller tests prove that one seller cannot unlock another?
- Does end-to-end verification inspect completed order shipping totals?
If the rule cannot answer those questions, “free shipping” is still a marketing label rather than a commerce capability.
The broader lesson
Medusa provides products, carts, calculated shipping options and fulfilment resources. A multi-vendor business adds another requirement: each supplier owns an independent delivery promise inside a shared buying journey.
We extended that foundation with a seller-level preference, seller subtotal aggregation and a small pricing override that leaves Medusa's normal delivery calculation intact. Property-aware discovery explains the offer. Checkout recalculates it. Multi-location fulfilment does not fragment the commercial threshold. Mixed sellers never subsidise one another.
The buyer gets one cart without being misled into one shipping contract.
That is what a marketplace promise should do: remain simple to read because the complexity has been resolved underneath it.