Chapter 27: Marketplace and Multi-Vendor Fundamentals

Why This Exists

Scaling a traditional e-commerce store is fundamentally limited by "Inventory Risk." If you want to sell 100,000 different products, you have to buy them, store them in a massive warehouse, and hope they sell. If they don't, you go bankrupt. A Multi-Vendor Marketplace exists to bypass this physics problem. By allowing third-party vendors to sell on your platform, you offer infinite product selection to buyers while taking zero inventory risk. You monetize the traffic, not the goods.

Real World Problem

A successful single-vendor store decides to allow other brands to sell on their site. A developer simply adds a vendor_id column to the products table. A customer adds a shirt (from Vendor A) and a hat (from Vendor B) to their cart. The system breaks immediately:

How much is shipping? Vendor A ships from New York. Vendor B ships from China.
Who gets the money? The payment gateway is hardcoded to send all money to the platform's bank account. The real-world problem is that transitioning from B2C to a B2B2C Marketplace fundamentally breaks every assumption about carts, orders, and payments.

Everyday Analogy

Standard E-commerce: A bakery. The owner buys the flour, bakes the bread, sells the bread, and keeps all the money.
Marketplace: A farmer's market. The organizer doesn't own any tomatoes. They just rent out tables. A customer walks from table to table buying things. The organizer makes money by charging the farmers a table fee or a percentage of their sales.

Beginner Explanation

A marketplace connects Buyers with Sellers. Examples: Amazon, Etsy, eBay, Uber, Airbnb. Instead of the website owning the products, independent sellers create accounts and list their own items. When a buyer buys an item, the website takes a small cut (commission) and passes the rest of the money to the seller. The seller is responsible for shipping the item to the buyer.

Intermediate Explanation

Architecturally, a marketplace is a Multi-Tenant System. The database must be designed to strictly isolate data. Vendor A must never be able to see Vendor B's sales.

The biggest architectural change is Order Splitting. In standard e-commerce, 1 Checkout = 1 Order. In a marketplace, 1 Checkout = 1 Parent Order (what the buyer sees) + N Sub-Orders (what the vendors see). If a cart contains items from 3 vendors, the system must generate 3 distinct sub-orders. Each vendor logs into their dashboard, sees only their specific sub-order, and provides a tracking number for their specific box.

Advanced Explanation

The most complex element of a marketplace is the Flow of Funds and the concept of the Merchant of Record (MoR).

Platform as MoR: The buyer's credit card statement says "Etsy." Etsy takes the legal responsibility for the sale, collects the tax, takes the money, holds it in escrow, and later initiates a "Payout" to the vendor minus the commission. This requires complex ledger accounting and massive legal compliance.
Vendor as MoR: The platform just acts as a pure software router (like Shopify). The buyer's credit card is processed directly against the Vendor's own Stripe account. The platform automatically extracts its fee during the transaction.

Modern marketplaces use specialized routing APIs (like Stripe Connect) to instantly split the $100 payment at the gateway level: $10 directly to the Platform, $90 directly to the Vendor, bypassing the platform's bank account entirely to reduce regulatory liability.

Real World Example

Airbnb: Airbnb manages the ultimate multi-vendor architecture. The "Vendor" provides a house. The "Buyer" wants a bed. Airbnb handles the trust (reviews, identity verification) and the complex fund routing. They collect the money when the guest books, but they hold it in escrow and do not release the payout to the host until 24 hours after the guest checks in, protecting the buyer from fraud while ensuring the vendor gets paid.

Architecture Design

Here is the flow of an Order Split in a Marketplace:

graph TD
    Cart[Customer Cart: Item A + Item B] --> Checkout[Checkout Process]
    
    Checkout --> Payment[Payment Gateway]
    
    Payment --> ParentOrder[Parent Order #100 - Total: $100]
    
    ParentOrder --> Splitter[Order Splitting Engine]
    
    Splitter --> SubOrderA[Sub-Order #100-A (Vendor 1) - $60]
    Splitter --> SubOrderB[Sub-Order #100-B (Vendor 2) - $40]
    
    SubOrderA --> DashA[Vendor 1 Dashboard]
    SubOrderB --> DashB[Vendor 2 Dashboard]

Database Design

1. The Vendors Table:

CREATE TABLE vendors (
    id UUID PRIMARY KEY,
    business_name VARCHAR(255),
    contact_email VARCHAR(255),
    status VARCHAR(50) -- 'PENDING', 'ACTIVE', 'SUSPENDED'
);

2. The Split Order Model:

CREATE TABLE parent_orders (
    id UUID PRIMARY KEY,
    customer_id UUID,
    grand_total DECIMAL(10,2) -- What the customer paid
);

CREATE TABLE vendor_orders (
    id UUID PRIMARY KEY,
    parent_order_id UUID,
    vendor_id UUID,
    subtotal DECIMAL(10,2), -- What this specific vendor earned
    shipping_cost DECIMAL(10,2),
    status VARCHAR(50), -- 'PENDING', 'SHIPPED'
    FOREIGN KEY (vendor_id) REFERENCES vendors(id)
);

(Line items are now attached to the vendor_orders, not the parent_orders).

API Design

Vendor Dashboard API (Implicit Filtering): GET /api/vendor/orders The backend automatically extracts the vendor_id from the JWT token and appends it to the SQL query: SELECT * FROM vendor_orders WHERE vendor_id = {extracted_id}. You never pass the vendor_id in the API URL (/api/vendor/123/orders), as that leads to IDOR vulnerabilities.

Production Considerations

The Chicken and Egg Problem: A marketplace is a two-sided network. Buyers won't visit if there are no vendors. Vendors won't list products if there are no buyers. Launching a marketplace requires solving this business problem, often by subsidizing one side initially (e.g., paying vendors to list).
Shipping Complexity: If a user buys from 3 vendors, they might be charged $5 shipping from each. A $15 shipping fee on a $30 order will cause cart abandonment. Marketplaces must heavily optimize how shipping is presented in the UI to avoid sticker shock.

Security Considerations

Tenant Isolation: The most critical security requirement. Every single database query related to products, orders, or customers in the vendor portal MUST include a WHERE vendor_id = ? clause. If a developer forgets this, Vendor A can view or edit Vendor B's data, instantly destroying the platform's credibility.

Common Mistakes

Assuming a Single Shipping Origin: Calculating shipping from the platform's headquarters instead of the individual vendor's zip code.
Handling Payouts Manually: Trying to export a CSV at the end of the month and doing manual bank transfers to pay vendors. This scales to maybe 50 vendors before the accounting team collapses. Payouts must be automated via APIs.

Tradeoffs and Alternatives

Curated vs. Open Marketplaces:
- Curated (e.g., Farfetch): Vendors must apply and be manually approved. High quality, zero spam, but slow growth.
- Open (e.g., eBay): Anyone can sign up and sell in 5 minutes. Massive growth, but requires huge investments in fraud detection and moderation to keep scammers out.

Interview Questions

Explain why a shopping cart in a multi-vendor marketplace is architecturally more complex than a cart in a standard e-commerce store.
What is "Order Splitting," and how would you design the database tables to support it?
How do you ensure that a vendor logging into the API can only see their own orders and not orders belonging to a competitor?

Hands-On Exercise

Go to Etsy.com.
Add an item from "Shop A" to your cart. Add an item from "Shop B" to your cart.
Go to the checkout page. Notice how the UI visually separates the items into two distinct groups, each with its own "Leave a note for the seller" box and its own shipping calculation. This UI reflects the underlying database "Sub-Order" architecture.

Key Takeaways

Marketplaces eliminate inventory risk by allowing third parties to sell on the platform.
The core architectural shift is Order Splitting (1 Checkout = Multiple Vendor Orders).
Strict Tenant Isolation (Row-Level Security) is mandatory to prevent cross-vendor data leaks.
Fund routing is complex; platforms must decide if they take legal liability (MoR) or just act as a software router.