DEV3 Vendora – Multi-Vendor Marketplace Laravel Script with Vendor Shops, Commissions & Payouts

The engineering behind Vendora, the DEV3 Laravel suite's multi-vendor marketplace: Laravel 12 and Filament 4 on a shared core, one pricing engine for split carts, commission from the most specific rule, a vendor ledger with a hold period, payouts, refunds that reverse the money and a REST API.

The problem it solves

A single-shop store has one seller, one shipment and one bank account. A marketplace has many of each, and the money has to be right for all of them at once. One cart holds products from several shops, so shipping has to be priced per package, a coupon has to be split fairly across lines from different sellers, and tax has to be charged on the discounted price. Commission depends on who is selling and what: a founding seller may have a special rate, digital goods may carry a higher one, and the rate on a sub-category should fall back to its parent. Vendors are paid out of what they earned, but a refund can arrive after the sale, so earnings need a hold period, and the same balance must never be withdrawn twice. A refund then has to undo all of it: the customer's money, the vendor's earning, the marketplace's commission and the stock. Digital files have to reach only the people who paid for them. And because Vendora is sold as a script, all of this had to install from a zip on ordinary PHP hosting, with no Node.js, no guaranteed queue worker, one cron entry at best and a web installer instead of a terminal, while reusing the shared DEV3 Laravel core built with Deskly.

Architecture and approach

Vendora is a Laravel 12 application with three Filament 4 panels on one user table: /admin for marketplace staff, /vendor for the seller centre and /account for customers. Each user reaches only the panels their role allows. The storefront is Blade with a small vanilla-JS layer for the cart drawer, search suggestions and motion, which keeps the public page at 35.2 KB of gzipped JS and CSS.

A shared DEV3 core

• One package, five products. Everything that is not about selling comes from dev3/laravel-core: the installer, typed and encrypted settings, branding, the Blade UI kit, motion and 3D helpers, demo mode, roles and permissions, the audit log, the payment gateways, backups, system health, Sanctum tokens, two-factor sign-in and English / Arabic with RTL. Vendora registers its four roles, six demo logins, its permissions, the Marketplace and Storefront settings groups and its two 3D presets through a product manifest. The packaging script copies the core into the zip, so buyers get one self-contained download.

Key design decisions

• One pricing engine, one order of operations. A single PricingEngine turns cart lines into a quote in a fixed order: split the lines by vendor, apply the coupon, price shipping per package from the destination country's zone, tax each line after its discount (and the shipping, where a rate says so), then work out the commission per line. The same class prices the cart drawer, the cart page and checkout, and its result is frozen onto the order and its lines, so the totals never drift between screens. The demo seeder pushes every one of its orders through the same engine.
• Money in integer cents, allocated exactly. Every price, discount, tax, commission and payout is an integer in the store currency's minor unit. A coupon's discount is spread across the eligible lines by largest remainder, so the line discounts always add up to the coupon. A shop coupon only touches that shop's lines, a percentage coupon can be capped, and a free-shipping coupon clears the shipping of the packages it covers.
• Commission from the most specific rule. CommissionResolver checks a vendor rule or the vendor's own rate first, then walks up the product's category lineage looking for a category rule or a rate on the category, then a global rule, and finally the default in Settings. A rule can add a fixed fee per line, and the commission can never exceed the line. It is charged on the price after discount, without tax or shipping, and the rate is stored on each order line, so a later rule change never rewrites past sales.
• A ledger, not a balance column. Every money movement for a shop is a signed row with an available_at date. A sale's earning (items after discount, minus commission, plus shipping, plus tax when vendors keep it) becomes available after the hold period, 7 days by default. The withdrawable balance is the sum of rows whose date has passed, so earnings clear without a cron job. A payout request locks the vendor row, checks the minimum, the available balance and that no other request is open, then writes the debit at once, so the same money cannot be requested twice; a rejection writes it back.
• Two ways to pay a vendor. Admins mark a payout paid with a bank or PayPal reference after sending the money themselves. For a vendor on Stripe Connect with an acct_… id, leaving the reference empty makes Vendora call the Stripe Transfers API with the secret key from Settings and store the transfer id as the reference.
• Payment confirmation that is safe to repeat. Marking an order paid is idempotent: a repeated gateway webhook returns early. In one transaction it reduces stock (per variant), redeems the coupon, credits each shop's ledger, delivers digital-only packages, notifies every shop and rolls the order status up.
• Refunds that undo the money, not only the status. A refund can cover some units of one line. For each line the shop's earning is reversed and the matching share of the marketplace commission is given back; when the whole package comes back, the shipping is refunded too. The shop gets one negative ledger row that records the gross and the commission returned, the gateway refund is capped at what is still refundable, stock is optionally restored, and the order rolls up to partially refunded or refunded.
• Tokenised digital downloads. Digital files live on the private disk and never get a public URL. Each purchased line gets its own download token. The download route checks that the order is paid and the line is not fully refunded, enforces the product's download limit and counts every download, so refunding an item also closes its link. The core's backups include storage/app/private and its media library hides private files, so digital products are backed up without ever being listed.
• A read-only API scoped to the token. /api/v1 runs on Sanctum. Products, a product by slug and the approved shops are public, behind a 60-requests-a-minute limit per IP; a shop's profile never exposes owner or payout details. With a token, a customer reads only their own orders (another customer's order number returns 404, not 403) and an approved vendor reads only their own shop's packages with commission and earnings, enforced by policies and a 120-a-minute limit per user. Every path is in the OpenAPI spec.
• Two-factor sign-in from the core. Filament's MFA is wired once in the DEV3 core: an authenticator app with 8 single-use recovery codes, or email codes. /admin honours a Require 2FA for staff setting, while the seller centre and customer account keep it optional. Super admins can reset a user's 2FA (audit-logged), php artisan dev3:2fa-reset rescues a locked-out owner, and the one-click demo logins never see a challenge.
• Moderation at the edges. A seller application creates a pending shop; approval, rejection with a reason and suspension, which hides every product of the shop at once, are all emailed. New vendor products can wait in an approval queue, reviews can be held for moderation, and only buyers of a delivered item can leave a review.
• An installer instead of a README. If .env is missing the app creates it and an APP_KEY, then redirects to a 5-step /install wizard: requirements, database (MySQL or SQLite, tested before writing), demo or empty data, admin account and a lock file. php artisan dev3:install does the same over SSH. vendor/ and public/build ship in the zip and the queue defaults to sync, so one cron entry is the only server setup.
• Demo data made by the real services. The seeders build a deterministic "Vendora Market": 12 approved shops plus 3 applicants and 1 rejected application, 191 products with 285 variants, 60 customers, and 597 orders over about eight months in every status, with 958 shop packages, a ledger row for every movement, about 540 reviews, refunds and monthly payouts, 6 shipping zones and 31 tax rates. The orders go through the pricing, order, refund and payout services, so the demo's numbers reconcile. Product images, shop logos and banners are SVG drawn by code (35 product kinds, 4 views each), so nothing in the demo carries a third-party licence.

The 3D and motion approach

• A product orbit in the hero. Rounded product cards, textured with the generated studio art, circle a glass pedestal on a tilted ring like a rotating shop shelf. The scene tilts with the pointer and relights for dark mode.
• An orders globe on the admin dashboard. A dotted Earth built from simplified land outlines carries a glowing pillar for each destination country, sized by its orders in the last 90 days, with animated arcs that flow from the shops' countries to the buyers.
• Cheap by default. three.js loads lazily as its own 187 KB chunk, the device pixel ratio is capped, scenes pause off-screen, reduced motion is respected, and an SVG poster shows without WebGL or when 3D is switched off in Settings → Branding.
• Motion without a licensing question. Reveals, counters, the flash-deal countdown and the fly-to-cart animation come from the core's data-attribute motion.js and a small store script with Lenis smooth scrolling, not GSAP, which keeps resale licensing simple.

Quality gates and results

Vendora 1.0.2 passed all seven release gates of the DEV3 Laravel suite, run by one script against the packaged build:

• Static analysis: composer validate, Pint clean, Larastan level 6 with 0 errors, and php -l on 316 files.
• Tests: 89 Pest tests with 533 assertions, including required money-path suites for the cart split, commission, coupons, tax, shipping, checkout, payouts, refunds and the API's cross-customer and cross-vendor authorisation, plus the core's two-factor tests.
• Front-end budget: 13.0 KB of JS and 22.2 KB of CSS gzipped on the public page (35.2 KB against a 180 KB budget), with the 187 KB three.js chunk loaded only when a scene needs it.
• Databases: the demo and empty seeders run on both MySQL 8.4 and SQLite; the demo seed writes 597 orders, 1,426 order lines, 958 shop packages and 536 reviews.
• Browser checks: 122 pages in headless Chrome with 0 console errors, plus 4 happy paths: a multi-vendor checkout with a simulated payment and tracking, a vendor shipping a package, a seller application approved by an admin, and a customer review.
• Installer: the release zip unzipped into a clean folder, installed through the /install wizard on MySQL with demo data, then signed in as the admin.
• Secret scan: 18,885 files in the 21 MB release zip, clean, and every text file inside it is scanned again when the listing is published.

The 118 screenshots and the two video tours were captured from the seeded demo across all three panels, light and dark mode, Arabic, tablet and phone, and they double as the listing's demo. They follow the money step by step: a two-shop cart, the vendor's fulfilment, a refund reaching the ledger, and a payout from request to payment.

Known gaps in 1.0.2 are listed openly: there is no product Q&A, vendor-to-customer messaging or multi-currency display; the REST API is read-only; and the PayPal and Razorpay drivers and the Stripe Connect transfer have not been run against live accounts.

Tech stack

Inside the build

Home page with a rotating 3D product orbit — Featured products circle a glass pedestal in a GPU-rendered hero that tilts with the cursor and counts up live marketplace stats.

Shop by category — Colourful category tiles with generated studio art lead into a nested category tree with any number of levels.