Guide chapters
The marketplace model comes before features
The problem#
The most common mistake when building a marketplace is not a technical one. It is that the catalogue, the cart and payments get built before anyone settles who actually sells, who takes the money, who ships and who answers a complaint.
Those answers are not a configuration setting. They go into the data model and stay there for years. Changing any of them after launch means migrating orders, payments and history, which is exactly the data you cannot afford to lose.
Six decisions made at the start#
| Decision | What it settles | How hard to undo |
|---|---|---|
| Who sells to the buyer: the platform or the user | consumer obligations, sales document, returns, payment model | very hard |
| Whether one cart can hold goods from several sellers | order model, payment split, shipping, returns | very hard |
| Who owns the product card: the platform or the seller | catalogue, moderation, imports, duplicates | hard |
| Who ships the goods | shipping, costs, fulfilment state, returns | expensive |
| Standalone marketplace or one bolted onto an existing store | catalogue, accounts, permissions, data migration | hard |
| Whether sellers run their own external shops | integrations, source of truth for stock and prices | moderate |
Minimum version#
To start you need those six decisions settled, written down and reflected in the data model. That takes no code beyond making the entities aware of who owns what.
- Every order line knows its seller, even if an order always has one today.
- A product knows the seller who listed it.
- Stock knows its owner, not just its product.
- A payment knows how it splits across sellers, even when the split has one element.
What not to build yet#
- A business-model configurator. You pick one model, you do not build a platform that supports all of them.
- An abstraction over the payment provider before you have a second provider.
- A canonical catalogue with listing deduplication, until duplicates are a real problem.
- Multi-warehouse handling, while the seller does the shipping.
Plan ahead#
Three things are cheap now and expensive later, whichever model you pick.
Ownership at line level, not order level#
An order may have one seller today. The data model does not have to assume it. Attaching the seller to the order line is neutral for the single-seller version and sufficient for the multi-seller one.
Snapshots rather than references for transactional data#
The product title, the price, the commission rate and the seller identity shown to the buyer should be recorded at purchase time. Reading them later from live records means a historical order changes whenever the catalogue does.
External identifiers separate from your own#
If there is even a plan to connect seller shops, a product needs somewhere to keep the identifier from the source system, separate from your own. Bolting that onto a general-purpose field later works, but mapping and conflict detection turn into guesswork.
Triggers#
Concrete events that send you back to the decisions in this chapter:
- a buyer asks for the first time why they have to place two separate orders;
- the first seller asks whether they can list goods from their own shop;
- the first complaint where nobody is sure who should handle it;
- the first refund after money has already gone out to a seller;
- a second person starts making operational decisions.
Common mistakes#
| Assumption | Why it costs |
|---|---|
| "An order has one seller." | A multi-seller cart then requires migrating every historical order. |
| "Commission is one number in settings." | The first rate change breaks the settlement of orders placed before it. |
| "A seller product and a product from their shop are the same thing." | At the first integration nobody knows which record is the source of truth. |
| "A successful payment means the order was created." | Money taken, no order, and the state has to be reconstructed by hand. |
| "The terms decide who is responsible." | The data model still has to know who is party to each transaction. |
What works in practice#
The decision with the widest consequences in the system I run in production turned out to be attaching the seller to the order line rather than to the order. That single relationship later shaped the payment split, settlements, refunds and payouts, and every one of those modules was built long after the catalogue.
The second such decision was snapshotting settlement data at purchase time. Without it, every change to a commission rate or a product price would retroactively change settlement values that must not move.
Checklist#
- It is clear who sells to the buyer, and the interface shows it.
- The order line knows its seller, regardless of today cart model.
- Data needed for settlement is recorded at purchase time, not read later.
- A product has somewhere to keep an external system identifier.
- It is clear who handles a complaint before the first one arrives.
- None of the six decisions is deferred to "we will sort it out later".
I design multi-vendor platforms with onboarding, payments, moderation, and operational workflows.
Explore marketplace development