- Creating a supplier account is easy.
- The seller may have no usable business address for an invoice.
- All of those suppliers can authenticate.
- For a multi-vendor marketplace built on Medusa, we designed onboarding as a live readiness contract.
The client problem
Creating a supplier account is easy. Making that supplier operational is not.
The seller may have no usable business address for an invoice. They may have created a warehouse without a shipping option. They may accept purchase orders but not card payments. Their payment account may still be disconnected. They may have accepted an old version of the marketplace terms. They may not have listed a single product.
All of those suppliers can authenticate. None should be treated in exactly the same way.
For a multi-vendor marketplace built on Medusa, we designed onboarding as a live readiness contract. The backend inspects the seller's real store, legal, delivery, payment and catalogue state. The dashboard turns those facts into an ordered checklist. Critical journeys remain gated until the capabilities needed to trade are present.
The question is no longer “did the supplier finish a form?” It is “can this supplier perform the business journey they selected?”
The client problem: registration and readiness are different states
Marketplaces often compress onboarding into one boolean: completed.
That flag is convenient, but it becomes unreliable as soon as the underlying business changes. A seller can delete its only shipping option after completing onboarding. The marketplace can publish new terms. A payout connection can become necessary after the seller enables a direct payment method. A business address can become incomplete after an edit.
If the flag remains true, the interface says the supplier is ready while the order journey says otherwise.
We treated readiness as a set of independently explainable capabilities. Store information must support commercial documents and geography. Delivery must connect a location to a sellable shipping option. Legal acceptance must refer to the current documents. Payment connectivity depends on the payment methods the supplier chose. Catalogue presence is visible as progress.
This makes onboarding useful after the welcome screen. It becomes an operating health model for the supplier account.
Recalculate from the domain instead of trusting a checkbox
The supplier onboarding endpoint does not read one completion flag. It gathers the current facts each time readiness is requested.
It loads seller preferences, document settings, seller fulfilment relationships, payout onboarding, the canonical terms and privacy documents, and an existence check for linked products. Independent reads run in parallel because none needs the result of another.
The product check deliberately asks whether a non-deleted seller product exists. It does not fetch a supplier's entire catalogue merely to call .length. That keeps the readiness question small even when the catalogue grows.
The response returns separate booleans for store information, products, locations and shipping, Stripe Connect, payment setup, terms and privacy. It also returns payment choices and the current and accepted legal versions.
The dashboard can therefore say what is missing. Operations can investigate one capability. New business rules can evolve without redefining an opaque global flag.
Store information must be usable downstream
“Store profile complete” cannot mean that the seller typed a display name.
The marketplace needs information for packing slips, invoices, receipts and geographic restrictions. The readiness check therefore looks for the seller name plus a company name, address line, city, postal code, province and country code in the commercial document address.
Each field has a downstream reason. Province and country make seller geography unambiguous. Postal address fields make generated documents usable. Company and seller names connect the marketplace identity with the legal or trading identity shown to buyers.
This avoids a common onboarding trap: collecting attractive profile content while discovering during the first order that the operational address is unusable.
The seller checklist sends the user directly to store settings to complete the missing data. Readiness is not a lecture about the data model; it is a path to the capability the business still needs.
A warehouse is not yet a delivery promise
Adding a stock location does not prove that a buyer can receive anything.
In Medusa, fulfilment is a connected topology. For this marketplace, supplier delivery readiness requires at least one seller stock location, a fulfilment set connected to that location, a service zone inside that set and a shipping option inside the zone.
The readiness API checks every link. A supplier with a named warehouse but no service zone is not marked ready. A zone with no shipping option is still incomplete. The dashboard describes the task in business language—set up locations and shipping—and takes the supplier to the relevant settings.
This matters because the missing middle is where many first orders fail. Inventory may exist, but no commercial delivery method can be selected for the buyer's destination.
By checking the whole path, onboarding tests the ability to offer fulfilment rather than the existence of an isolated configuration record.
Payment readiness depends on the seller's business model
Not every supplier gets paid in the same way.
The platform lets sellers choose supported methods such as purchase orders, direct checkout and instant payment. At least one method must be selected, and unknown values are rejected.
Direct checkout and instant payment require a connected payout path, so those choices make Stripe Connect part of critical onboarding. A supplier that works only through purchase orders does not need to complete a card-payment connection merely to access the marketplace.
This conditional gate is important. A universal Stripe requirement would add irrelevant friction for suppliers whose buyers pay against approved invoices. Omitting the connection for a direct-payment seller would create a much worse failure after checkout.
The system derives the requirement from the selected commercial model. Onboarding adapts to how the supplier intends to transact instead of forcing every seller through the same generic funnel.
Legal acceptance must name the version
A timestamp tells us that a supplier accepted something. It does not tell us whether they accepted the terms currently governing the marketplace.
Seller preferences store separate acceptance timestamps and document versions for terms and privacy. The legal-document module exposes the current canonical version of each document. Readiness is true only when an acceptance exists and its stored version matches the current version.
When the marketplace publishes a new version, the comparison becomes false. The dashboard reopens the legal step and presents the current documents for acceptance.
That gives the product a clean operational rule: access follows current acceptance, not the historical fact that a checkbox was clicked once. Terms and privacy also remain separate, so accepting one does not silently stand in for the other.
The UI can show when and which version was accepted, making the state understandable to the supplier and support team.
Turn readiness into a guided checklist
The supplier dashboard presents the work as a sequence rather than an error wall.
It starts with current terms and privacy, then store information. Stripe Connect appears only when the chosen payment methods require it. Locations and shipping follow, then the first product import. The interface highlights the first incomplete step, shows completed items and provides one direct action for the current task.
Progress is calculated from the visible steps, so a purchase-order seller is not penalised for a card-payment step that does not apply.
This structure reduces cognitive load. A new supplier does not need to understand Medusa's seller, stock-location, fulfilment-set and service-zone modules. They see the business outcome: tell us who you are, accept the current marketplace rules, connect the money path you chose, explain where you fulfil from and add products.
The architecture stays beneath the journey while still enforcing it.
Distinguish guidance from activation gates
Not every useful checklist item must block the whole supplier dashboard.
At this repository baseline, critical access requires current terms and privacy, complete store information, complete locations and shipping, and Stripe Connect when the selected payment methods need it. Incomplete suppliers can use the dashboard and named onboarding routes; other routes redirect them back to the checklist.
Product presence is displayed as onboarding progress but is not part of that critical route gate. Payment-method selection is represented by the API, while its hard-gate line is not active in the protected route.
That distinction matters to the seller experience. Some steps establish the minimum safe operating account; others guide the seller toward becoming commercially useful. The interface can show both without pretending that every green circle represents the same kind of control.
The business can tighten those policies later because each readiness predicate already has a clear source.
Re-entry matters as much as first-time onboarding
Readiness can move backwards for legitimate reasons.
A new legal version makes acceptance stale. Removing the final shipping option breaks the fulfilment topology. Enabling direct payments creates a new connection requirement. Editing the commercial address can make required document fields incomplete.
Because status is recalculated from live state, the dashboard can bring the supplier back to the relevant step. The protected route does not assume that a seller who once passed onboarding stays ready forever.
This is healthier than a one-way wizard. The marketplace can evolve its rules and supplier configuration can change without creating a separate compliance audit system just to discover the account is no longer operational.
Re-entry also gives support a shared language: legal, store, payment, shipping or catalogue. The missing capability is visible instead of hidden behind “account inactive”.
Keep the backend as the authority
The checklist is a helpful interface, not the security boundary.
The protected supplier route consumes current onboarding state and redirects an incomplete seller away from unrelated application pages. The readiness API derives that state from server-side seller identity; it does not accept an arbitrary seller ID from the browser.
The legal acceptance service records the canonical document version. Payment setup validates allowed methods. Store and fulfilment checks come from backend relationships. The browser cannot mark a step complete by changing local state.
This separation keeps the experience responsive without turning presentation into authority. The dashboard may animate progress and deep-link to settings, but the next server response decides whether the capability actually exists.
For a multi-vendor marketplace, that is essential: one supplier's readiness data must never be selectable by another supplier's client request.
Why this fits Medusa
Medusa already provides the commerce primitives behind the journey: sellers, products, stock locations, fulfilment sets, service zones, shipping options and payout-account relationships.
The client's marketplace needed a layer that translated those primitives into supplier-operating readiness. We added seller preferences for payment and legal state, commercial document settings, the aggregate readiness endpoint and a dashboard gate built around the resulting contract.
This is why choosing an extensible commerce engine matters. We did not force suppliers through a generic SaaS wizard disconnected from trading reality. We could ask Medusa and the marketplace modules whether the capabilities actually existed.
The platform remains responsible for commerce. The onboarding layer explains which parts of that commerce setup are ready and guides the supplier to complete the rest.
The supplier-readiness checklist
Before calling a supplier active, ask:
- Is readiness recomputed from current domain state?
- Does store information support invoices and geographic rules?
- Is there a stock location?
- Does it connect to a fulfilment set?
- Does a service zone contain a shipping option?
- Has the supplier selected at least one supported payment method?
- Which methods require a payout connection?
- Are purchase-order suppliers spared irrelevant card onboarding?
- Were both terms and privacy accepted?
- Do accepted versions equal the current canonical versions?
- Will a document update reopen acceptance?
- Which checklist items are guidance, and which gate access?
- Can an incomplete supplier reach the pages needed to recover?
- Does the backend, rather than the browser, decide readiness?
- Can support identify the exact missing capability?
The answers turn onboarding from a ceremony into an operating contract.
The broader lesson
A supplier account is not the same thing as a supplier ready to trade.
For this marketplace, readiness comes from real capabilities: current legal acceptance, a usable commercial identity, a complete delivery topology and the payment connection required by the chosen transaction model. Product presence and payment choices remain visible as their own progress signals.
The dashboard tells the seller what to do next. The backend recalculates whether the work is actually complete. If the marketplace terms or supplier configuration changes, onboarding can reopen at the correct point.
That creates a better first experience, but it also creates a safer ongoing marketplace. Buyers meet suppliers whose operating setup is coherent, suppliers are not forced through irrelevant steps, and the platform can explain every readiness decision in business terms.