Headless Multi-Vendor Marketplace

Project overview

This marketplace connected independent vendors with customers across home, lifestyle, electronics, and personal-care categories. The original monolithic storefront made every merchandising change dependent on backend releases, while vendor onboarding and commission calculations required significant manual work. I led a headless rebuild that gave customers a faster Next.js experience and operators a clearer vendor, catalog, and settlement workflow.

Unlike a single-store commerce application, the platform had to treat product ownership, vendor availability, split fulfillment, returns, and commission rules as first-class concerns.

Problem statement

Customers experienced slow category pages and inconsistent stock. A single cart could contain items from several vendors, but delivery estimates and return rules were presented as if every item shipped together. Vendors submitted catalogs through spreadsheets, and administrators manually checked missing attributes and image quality. Finance teams reconciled commissions after payouts using separate exports.

The replacement needed independent storefront iteration, accurate inventory reservation, vendor-scoped access, and an auditable ledger from customer charge through vendor settlement.

Solution and architecture

Next.js delivered server-rendered category and product pages with cached catalog data and incremental revalidation. TailwindCSS components supported consistent product cards, price states, filters, seller information, and responsive checkout. Search-friendly URLs, structured product data, canonical metadata, and optimized images improved discovery as well as performance.

The Node.js service layer separated catalog, inventory, order, payment, vendor, and settlement domains. MongoDB stored flexible category attributes while validation rules prevented incomplete listings from publishing. Redis coordinated short inventory reservations and cached high-traffic collections.

Checkout split a cart into vendor fulfillment groups but maintained one customer-facing order. Prices, taxes, commissions, and shipping allocations were captured in an immutable ledger:

const vendorOrders = groupByVendor(validatedCart.items);
const ledger = calculateLedger(vendorOrders, commissionRules);

await createPendingOrder({ customerId, vendorOrders, ledger });

Signed payment webhooks were processed idempotently. Settlement jobs paid only delivered, return-window-complete items and recorded every adjustment, making finance reconciliation possible without recomputing history from current product data.

Vendor and customer capabilities

• Guided vendor onboarding with identity, banking, policy, and catalog checks.
• Category-specific listing forms with draft and review states.
• Bulk catalog import with row-level validation feedback.
• Faceted search, seller filters, wishlists, coupons, and persistent carts.
• Vendor-aware delivery estimates, cancellations, returns, and notifications.
• Inventory, sales, commission, payout, and return dashboards.
• Admin moderation, exception queues, and marketplace-wide reporting.

Outcomes

Server-rendered pages, responsive imagery, and better cache boundaries improved median product-page load time by 34%. Mobile conversion increased by 22% during the measured release period. Guided forms and validation reduced average vendor onboarding time by 65%, while row-level import errors prevented poor catalog data from reaching customers.

Inventory reservations substantially reduced post-payment stock cancellations. The immutable ledger shortened payout reconciliation and gave support teams a precise explanation for vendor commissions, refunds, and adjustments. Headless boundaries also allowed merchandising changes to ship without coordinating a full backend release.

Key engineering decisions

Vendor isolation was enforced below the controller layer. Repository methods required a vendor scope, and administrative cross-vendor queries used a separate reviewed interface. This reduced the chance that a missing page filter exposed another seller's orders. Catalog moderation used explicit draft, submitted, approved, rejected, and suspended states; a simple published boolean could not represent why an item was unavailable or who needed to act next.

The storefront cached public product content but requested price and availability close to purchase. Cache keys included market and currency, and invalidation events followed approved catalog changes. Settlement was modeled as a ledger rather than a mutable payout total. Charges, commissions, returns, fees, and manual adjustments remained individual entries whose sum produced the payable balance. That design required more upfront modeling, but it made partial returns and post-delivery disputes explainable to vendors and finance teams.

Related engineering work

Compare the multi-vendor model with the earlier scalable e-commerce platform. The frontend performance choices build on the benefits of Next.js, while the data-access strategy follows MongoDB performance tuning for modern apps.