Chapter 29: Vendor Store Management

Why This Exists

In a single-vendor e-commerce store, the engineering team or a few internal admins manage the product catalog. In a marketplace with 50,000 vendors, internal management is mathematically impossible. A multi-vendor architecture must include a self-serve Vendor Portal. This portal exists to give independent sellers the tools to run their own micro-businesses—managing inventory, fulfilling orders, and answering customer queries—autonomously, securely, and at scale.

Real World Problem

A successful marketplace launches, but they only build a basic UI for vendors to add products one by one. A major enterprise shoe brand wants to join the platform. They have 15,000 SKUs and their inventory changes every 10 minutes. When they see the manual UI, they laugh and walk away. The real-world problem is that a marketplace cannot attract high-volume, professional sellers without providing programmatic bulk management tools (APIs and CSV uploads) in the vendor portal.

Everyday Analogy

Think of a shopping mall. The mall management (the Marketplace) provides the building, the parking lot, and the security. But they don't arrange the mannequins in the Nike store. They give the keys to the Nike store manager (the Vendor). The manager has the autonomy to change prices, restock shelves, and decorate their specific store, but their key absolutely does not open the Adidas store next door.

Beginner Explanation

A Vendor Portal is a private dashboard just for the seller. When a seller logs in, they don't see the whole marketplace. They only see:

"My Products" (where they can add new items or change prices).
"My Orders" (where they can see who bought their stuff and print shipping labels).
"My Payouts" (where they see how much money the marketplace deposited into their bank account).

Intermediate Explanation

The defining architectural constraint of the Vendor Portal is Tenant Isolation (Row-Level Security).

Every single API endpoint serving the portal must implicitly filter data based on the authenticated user. When the frontend requests GET /api/vendor/products, the backend reads the JWT token, extracts vendor_id = 42, and rewrites the database query to SELECT * FROM products WHERE vendor_id = 42. The frontend should never send the vendor_id in the payload or URL, because a malicious vendor could easily change it to vendor_id = 43 to steal competitor data.

Advanced Explanation

At scale, the portal must support Multi-User Role-Based Access Control (RBAC) within a single vendor account. A large vendor might have a team of 10 people.

The Owner needs access to the "Financial Payouts" tab.
The Warehouse Worker only needs access to the "Orders to Fulfill" tab and should not see the bank details.

Furthermore, the portal must support Bulk Asynchronous Operations. If a vendor uploads a CSV with 10,000 product updates, the HTTP request cannot stay open while the database processes it. The API accepts the file, returns a 202 Accepted job ID, pushes the CSV to a background worker queue, and the UI polls for the status or relies on WebSockets to notify the user when the import is complete.

Real World Example

Amazon Seller Central: Amazon provides one of the most comprehensive vendor portals in the world. Sellers don't just add products; they manage advertising campaigns, generate barcode labels for FBA (Fulfillment by Amazon), respond to customer disputes, and integrate their own ERP systems via Amazon's SP-API (Selling Partner API). It is essentially an entire B2B SaaS platform embedded inside the marketplace.

Architecture Design

Here is the flow of a secure Vendor API request and an Asynchronous Bulk Upload:

graph TD
    UI[Vendor Dashboard] -->|1. GET /orders| API_GW[API Gateway]
    
    API_GW -->|Extracts JWT: vendor_id=5| AuthMiddleware
    AuthMiddleware -->|SELECT * ... WHERE vendor_id=5| DB[(Primary DB)]
    
    UI -->|2. POST /products/csv| API_GW
    API_GW -->|Save File| Storage[S3 Bucket]
    API_GW -->|Publish Job| MQ[Message Queue]
    
    MQ --> Worker[CSV Processing Worker]
    Worker -->|Validates & Inserts| DB
    Worker -->|Updates Job Status| Cache[(Redis)]
    
    UI -.->|Polls Job Status| Cache

Database Design

Every table that belongs to a vendor must have a foreign key linking it to the vendor.

CREATE TABLE products (
    id UUID PRIMARY KEY,
    vendor_id UUID NOT NULL, -- Critical for isolation
    title VARCHAR(255),
    price DECIMAL(10,2),
    stock_count INT,
    FOREIGN KEY (vendor_id) REFERENCES vendors(id)
);

CREATE TABLE vendor_users (
    id UUID PRIMARY KEY,
    vendor_id UUID NOT NULL,
    auth_user_id UUID NOT NULL,
    role VARCHAR(50), -- 'OWNER', 'FULFILLMENT_STAFF'
    FOREIGN KEY (vendor_id) REFERENCES vendors(id)
);

API Design

Fetch Vendor Orders (Implicit Isolation): GET /api/vendor/orders?status=PENDING (No vendor_id in the URL. Handled securely by middleware).

Bulk Product Upload: POST /api/vendor/products/bulk-upload Payload: multipart/form-data containing the CSV. Response: { "job_id": "job_999", "status": "PROCESSING" }

Production Considerations

Catalog Moderation: When a vendor clicks "Save Product," does it go live to millions of buyers instantly? If so, they might upload pornography or counterfeit goods. Most marketplaces place new products into a PENDING_MODERATION state. An automated Machine Learning image-scanner checks it, and if it passes, it flips to ACTIVE. If it's suspicious, it goes to a human moderation queue.
API Rate Limiting: Large vendors will write custom scripts to hit your APIs to update their inventory automatically. If you don't rate limit your vendor APIs (e.g., 50 requests per second), one badly written script by a vendor's intern will take down your entire marketplace.

Security Considerations

Cross-Site Request Forgery (CSRF) & XSS: Vendor portals are prime targets. If a vendor can inject an XSS script into their product description, and a Marketplace Admin views that product in the super-admin dashboard, the script can execute and steal the admin's session token, compromising the entire platform. Strict input sanitization is mandatory.

Common Mistakes

Forgetting Pagination: Building a UI that runs SELECT * FROM orders and displays them in a table. It works fine for new vendors. When a vendor hits 50,000 orders, the database query locks up, and the page crashes. Always enforce pagination (LIMIT 50 OFFSET 0) from day one.
Ignoring Developer Experience (DX): Failing to provide REST/GraphQL APIs or Webhooks for vendors. Enterprise sellers will not manually click buttons in a UI; they require APIs to sync your marketplace with their internal software (like Shopify or Magento).

Tradeoffs and Alternatives

Pre-Moderation vs. Post-Moderation:
- Pre-Moderation: Every product is checked before going live. High quality, zero illegal content, but extremely frustrating for vendors who have to wait 24 hours to fix a typo.
- Post-Moderation: Products go live instantly. ML bots and user reports flag bad content later. Highly scalable and vendors love it, but risks brand damage if illegal items are visible for a few hours.

Interview Questions

How do you design an API to ensure that Vendor A cannot accidentally or maliciously delete a product belonging to Vendor B?
A vendor wants to update the prices of 100,000 products using a CSV file. Architect the system flow so this action does not cause an HTTP timeout.
Why is it important to have multi-user RBAC (Role-Based Access Control) within a single vendor's account?

Hands-On Exercise

Design the column headers for a CSV file that a vendor would upload to bulk-create products (e.g., SKU, Title, Price, Quantity).
Think about what should happen if row 5,000 in the CSV has a negative price error. Should the system reject the entire file, or skip the error and process the other 9,999 rows? (Hint: The best UX is to process the good ones and return a specific error report for the bad ones).

Key Takeaways

Vendor Portals empower sellers to act autonomously, enabling the marketplace to scale infinitely.
Tenant Isolation (Row-Level Security) is the most critical architectural constraint. Never trust client-provided vendor IDs.
Professional vendors require bulk tools (CSV uploads, APIs, Webhooks) and internal RBAC for their staff.
Catalog items usually require an asynchronous moderation pipeline before becoming visible to buyers.