When you build a standard single-store e-commerce site, checkout is mostly straightforward arithmetic. A customer adds items to a cart, you add up the prices, apply a shipping flat rate or API quote, calculate tax, and hand the total off to a payment gateway.
Everything gets complicated the moment you introduce multiple vendors.
On NSMAH, an active multi-vendor marketplace built as a Next.js and TypeScript monorepo with MongoDB, TanStack Query, and Zod, the product catalog was working well, but the checkout experience had reached an impasse. Customers were buying products from three or four different merchants in a single transaction, and the existing checkout logic could not handle the logistical realities of multi-seller fulfillment.
The first major piece I had to design was delivery class management. When multiple independent vendors sell on the same platform, products do not share shipping rules. A small handcrafted accessory might ship in a padded envelope for a few dollars, while large home decor requires bulky parcel handling from a warehouse in another province.
I built an administrative interface where store managers could define custom delivery classes and assign them directly to product lines. The difficult part was wiring those rules into the checkout pipeline. When a shopper placed three items from two different vendors into their cart, the system had to group items by seller, calculate the correct delivery tier for each merchant's items, and present a clear, unified shipping breakdown to the customer. We also had to make sure vendor payouts and ledger balances split properly on the backend without breaking existing merchant settings.
Next came promotional discounts. A naive discount system simply subtracts a fixed dollar amount or percentage from the cart subtotal. On a multi-vendor platform, that approach creates immediate accounting chaos. If a customer uses a ten-dollar coupon on an order split between Vendor A and Vendor B, who absorbs that discount? Does the coupon require a minimum spend per seller or across the total cart?
I built a full-stack coupon validation engine that handled these rules cleanly. Administrators could configure expiration dates, usage limits, minimum order values, and specific promotional conditions. On the customer storefront, I built responsive coupon forms with descriptive error handling. When a valid code was applied, the system recalculated subtotals, tax rules, and vendor payout splits in real time so neither the customer nor the merchant ended up with unexpected surprises on their invoice.
The most frustrating issues, however, were not business logic. They were frontend state synchronization bugs.
During checkout, customers moved through a multi-step flow: reviewing the cart, selecting delivery addresses, picking shipping methods, and entering payment information. In several places, client state and server state fell out of sync during step transitions. A user would select a new shipping address, but the shipping calculation query would fire with stale address data, or Next.js would throw hydration errors because local browser storage diverged from server-rendered markup. In the worst cases, race conditions caused payment authorization buttons to remain disabled even after all required fields were filled.
Fixing this required auditing the state flow from scratch. I tightened our schema validation with Zod, unified address selection state inside TanStack Query cache keys, and ensured all calculations resolved deterministically before transition steps were marked valid. This eliminated the hydration mismatches and made the multi-step checkout predictable.
Because this was an active marketplace where broken checkout flows meant lost customer sales, pushing untested changes to production was out of the question. I containerized the entire monorepo using Docker and set up automated deployments through Coolify on a Linux VPS. This gave the client an isolated staging environment identical to production. We were able to run through dozens of multi-vendor edge cases, testing complex shipping combinations and coupon rules thoroughly before any code touched live customers.
Multi-vendor e-commerce is rarely about building fancy frontend animations. It is about getting the data boundaries right, keeping state strictly synchronized across complex multi-step forms, and making sure that when real money moves, every calculation is rock solid.