How to Start Up a Marketplace With VBWD

How to launch a two-sided marketplace on VBWD: enable vendor mode, onboard vendors, build catalogue and listing pages, wire checkout and tax, and pay commissions through a Stripe-Connect-style rail.

A practical, step-by-step guide.

A marketplace is a shop where you are not the only seller. Multiple vendors list their products, buyers check out once, and you take a cut of each sale before paying vendors their share. This guide walks through standing up that model on VBWD, a self-hosted, source-available platform built on Python/Flask, PostgreSQL, Vue 3, and Docker. You run it on your own infrastructure. Nothing here is a hosted account you rent by the seat.

The important design fact up front: VBWD keeps a deliberately agnostic core and pushes all domain behaviour into plugins. The marketplace itself is a plugin. It adds a vendor layer (“vendor mode”) on top of the ordinary shop, and it couples vendors to products through extra data (a vendor_id) rather than by editing core tables. That is why you can run a plain single-seller shop today and a multi-vendor marketplace tomorrow without forking anything.

What you will end up with

A product catalogue where each product is owned by a vendor.
Vendor onboarding, so sellers can register and list.
Catalogue and listing pages with working filters and pagination.
Checkout, tax, and invoicing through the shared billing engine.
Commission and payout tracking so each vendor gets their share.
Moderation controls so you approve who sells and what ships.

Prerequisites

A host that can run Docker and Docker Compose (a small VPS is fine to start).
PostgreSQL and Redis, both provided by the default Compose setup.
A domain name and TLS, because you will be handling checkout.
A merchant account with a payment provider that supports split payouts (a Stripe-Connect-style rail is the reference model).
Basic comfort with a terminal, environment files, and reading logs. The documentation covers install and configuration in more depth than this article.

On licensing: VBWD is distributed under BSL 1.1. It is free for commercial use while your annual VBWD-attributable sales stay under the value of 6.7 BTC (measured as the arithmetic average of daily BTC/USD over the reporting year). Above that, you need a commercial license. It is source-available, not public-domain, and not CC0 — read the terms on the pricing page before you build a business on top of it.

Step 1: Get the base platform running

Clone the SDK and start the backend with Docker Compose. The default stack brings up the Flask API, PostgreSQL, and Redis. Run the database migrations and confirm the API answers a health check before you touch anything marketplace-specific.

Do not skip the health check, and do not treat a 200 response as proof that your plugins loaded. A healthy API can still have a disabled or misconfigured plugin. You verify plugins separately, in Step 2.

Step 2: Enable the three plugins you need

A marketplace is a composition of plugins, not a single switch. You need at least three enabled together:

shop — the product, cart, and order machinery.
marketplace — the vendor layer that turns a shop into a multi-seller shop.
a payment plugin — the rail that actually captures money at checkout.

Plugin state lives in a single source of truth on the host (the plugins.json manifests bind-mounted into each container). Enable each plugin there, keyed correctly, and restart the API so the changes are picked up. Browse the full catalogue of available plugins on the plugins page to confirm which payment rail matches the provider you signed up with.

The ordering matters conceptually: the marketplace plugin assumes the shop plugin’s product model exists, because it attaches its vendor_id to shop products via extra data. Enable shop first, then marketplace, then payment.

Step 3: Onboard your first vendors

With vendor mode active, sellers become first-class actors. Onboarding a vendor means creating the vendor record and linking a user account to it. From then on, any product that vendor creates carries their vendor_id in its extra data. That single field is the whole coupling between a product and its seller — the core never gains a “vendor” column, and the shop plugin does not need to know vendors exist.

Practically, decide your onboarding policy now:

Open registration (anyone can apply to sell, you approve later), or invite-only.
What a vendor must provide before their listings go live.
Who at your company can approve a vendor. This is an RBAC decision, covered in Step 7.

Start with two or three real vendors, not fifty. You want to walk one full sale end to end before you scale onboarding.

Step 4: Build catalogue and listing pages

Buyers need pages to browse. VBWD builds these on top of the CMS, and the listing behaviour rides a shared filter-and-pagination contract so every list on the site behaves the same way. The contract is a predictable response envelope:

{ "items": [...], "total": 128, "page": 2, "per_page": 20, "pages": 7 }

Because filtering and pagination are a shared contract rather than per-page code, a category page, a vendor’s storefront, and a search results page all consume the same shape. You wire filters (price, category, vendor) against it and let the shared components handle the paging UI. Facet definitions that are specific to your domain live in the plugin, not the core. The architecture overview explains where the seam sits between the agnostic list mechanism and the domain-specific facets.

Give each vendor a storefront page filtered by their vendor_id, and give buyers at least one cross-vendor catalogue so the marketplace feels like one shop rather than many disconnected ones.

Step 5: Wire checkout, tax, and invoicing

Checkout runs through the platform’s billing engine, which is shared across every selling vertical rather than reimplemented per plugin. The engine computes the price, applies tax with a per-rate breakdown, produces the invoice, and captures payment through the payment plugin you enabled in Step 2.

For a marketplace, the thing to get right is that a single buyer cart can contain products from several vendors. The billing engine handles the money; the marketplace layer is responsible for remembering which line belongs to which vendor so you can compute commissions afterwards. Test a mixed cart — two vendors, one checkout — before you go live. Confirm the invoice totals, the tax breakdown, and that each line still carries its vendor_id.

Step 6: Set up commission and payouts

This is what separates a marketplace from a shop: you collect the money, keep a commission, and pay the rest to vendors. VBWD models this with a Stripe-Connect-style referral/connect rail behind a provider-agnostic port (IConnectProvider). The port means the commission logic does not hard-code one PSP; you implement or enable the provider that matches your payment rail.

Commissions move through an explicit lifecycle so you always know what is owed and what has settled:

pending — sale captured, commission calculated, nothing paid out yet.
confirmed — the sale is final (past refund window, fulfilment confirmed).
reversed — the sale was refunded or cancelled; the commission is unwound.
paid — the vendor’s share has been transferred.

Decide your commission rate and your confirmation trigger before you switch payouts on. A commission that jumps straight from pending to paid with no confirmed gate will pay vendors for orders that later get refunded, and clawing that back is painful.

Step 7: Add moderation with RBAC and access levels

You will need to approve vendors, take down bad listings, and limit who on your team can do those things. VBWD handles this through role-based access control and user access levels rather than a bolted-on admin flag. Define roles (for example: reviewer who can approve listings, finance who can release payouts, admin who can do both) and grant permissions to match.

Access levels also gate what a logged-in vendor can reach in their own dashboard versus what a buyer sees. Set these up before you open registration, because retrofitting permissions after real vendors are active means auditing live data.

Verification checklist

Before announcing anything, walk this list on a staging copy:

Shop, marketplace, and a payment plugin all show as enabled after an API restart — not just present, but enabled.
A new vendor can register, and their product carries the right vendor_id.
A catalogue page returns the {items, total, page, per_page, pages} envelope and paginates correctly.
A mixed-vendor cart checks out, produces one invoice, and shows the correct tax breakdown.
A completed sale creates a commission in pending, and a refund moves it to reversed.
A reviewer role can approve a listing but cannot release a payout.

Limits and honest caveats

The software gives you the mechanism. It does not give you the legal layer, and you should not pretend otherwise.

The moment you route money to vendors, you are running payouts, and that means you inherit your PSP’s KYC and onboarding requirements for every vendor you pay. Depending on where you and your vendors operate, you may also take on money-transmission and compliance obligations. VBWD’s connect rail gives you the technical means to hold funds, split them, and transfer them; it does not make you compliant. Talk to your PSP and, if the amounts are non-trivial, a lawyer, before you flip payouts on for real vendors.

You also operate the infrastructure. Self-hosted means the uptime, backups, security patches, and database health are yours. That is the trade for control and for source availability — nobody is watching your PostgreSQL instance but you.

Finally, none of the numbers in your business model come from the platform. The commission rate, the licence threshold math, your pricing — those are your decisions. VBWD gives you the lifecycle states and the ports; you supply the policy.

Takeaway

Starting a marketplace on VBWD is a composition exercise, not a rewrite: enable shop, marketplace, and a payment plugin; onboard vendors coupled by a single vendor_id; build catalogue pages on the shared list contract; run checkout through the billing engine; track commissions through their pending-to-paid lifecycle; and gate everything with RBAC. The core stays agnostic the whole way, which is what lets you grow from one seller to many without tearing anything down. Read the docs for the exact install and configuration commands, and confirm your licensing position before your sales cross the threshold.