Building a Two-Sided Marketplace on Bubble.io
The complete technical blueprint: buyer & seller flows, listing management, search & discovery, escrow payments with Stripe Connect, reviews & trust, dispute resolution, onboarding funnels, and production-grade security — built correctly in Bubble from day one.
What Makes a Marketplace Different — & Why It’s Harder Than a SaaS
A marketplace is a platform that connects two distinct user types — typically buyers and sellers (or hosts and guests, freelancers and clients, providers and consumers) — and facilitates transactions between them. Think Etsy, Fiverr, Airbnb, Upwork, and eBay. The platform takes a commission (or fee) on every transaction rather than charging a flat subscription.
Marketplaces are architecturally more complex than SaaS for a fundamental reason: you have two completely different user experiences to build (buyer and seller), two different onboarding funnels, payment flows that involve three parties (buyer, platform, seller), trust mechanisms (reviews, verification badges), and a cold-start problem where neither side has value without the other. Getting this architecture right in Bubble from day one determines whether your marketplace can scale — or whether you’ll be rebuilding everything after your first 500 users.
The Seven Pillars of a Marketplace on Bubble
Dual User Roles
Buyers and sellers are the same User data type but with different profiles, onboarding paths, and dashboards. A user can be both a buyer and a seller simultaneously.
Listing Management
Sellers create, edit, and manage listings. Listings have status (draft, active, paused, sold). Categories, tags, pricing models, availability, and media galleries all live on the Listing type.
Search & Discovery
Buyers discover listings via keyword search, category filters, price ranges, ratings, and location. Search performance is the single biggest driver of buyer conversion and must be architected carefully in Bubble.
Stripe Connect (Escrow)
Payments use Stripe Connect with the platform as the intermediary. Funds are captured from the buyer, held by the platform, then released to the seller’s connected Stripe account after delivery, minus the platform’s commission.
Messaging System
Secure in-platform messaging between buyers and sellers on a per-order basis. Messages must be scoped to an Order (not a listing) to prevent off-platform transactions and maintain dispute history.
Reviews & Trust
Bidirectional reviews: buyers review sellers, sellers review buyers. Reviews are only unlocked after order completion. Aggregate ratings on seller profiles drive discovery ranking and buyer confidence.
Dispute Resolution
When delivery is disputed, the platform mediates. Funds remain in escrow until resolved. The dispute system must trigger Stripe refunds or releases programmatically based on outcome decisions.
Order Lifecycle
Orders move through a defined status workflow: Pending → Accepted → In Progress → Delivered → Completed (or Disputed/Cancelled). Each status transition triggers notifications and payment actions.
Seller Analytics
Sellers need revenue dashboards, order history, payout tracking, and listing performance data. Buyers need order history, saved listings, and spend tracking. Two separate dashboard experiences from shared data.
Marketplace Architecture: The Full Stack
Buyer A
Buyer B
Buyer+Seller
Seller C
Listings · Orders · Messaging · Reviews · Disputes · Payouts
Marketplace Types You Can Build on Bubble
Physical or digital goods. Sellers list products with inventory, buyers purchase and receive. Examples: handmade goods, templates, stock photos, ebooks, plugins.
- ✓Inventory tracking per listing
- ✓Digital delivery (file download)
- ✓Shipping address collection
Freelancers and professionals offer scoped services. Examples: Fiverr clone, design marketplace, development services, consulting bookings.
- ✓Service packages with tiered pricing
- ✓Delivery milestones + revision rounds
- ✓Order brief / requirements intake
Spaces, equipment, or assets available for time-limited rental. Examples: Airbnb clone, equipment rental, parking spot rental, event venue booking.
- ✓Availability calendar per listing
- ✓Date-range booking with conflict detection
- ✓Security deposits & damage claims
Appointment-based or event-based transactions. Examples: tutoring sessions, fitness classes, beauty appointments, coaching calls.
- ✓Time-slot availability management
- ✓Calendar sync (Google Calendar API)
- ✓Reminder notifications
The Core Marketplace Data Model
The marketplace data model is the foundation every other decision sits on. Get these relationships wrong and you’ll be refactoring while live orders are in flight. These eight data types cover the complete foundation of any two-sided marketplace built on Bubble. Every additional feature you build will extend these types — not replace them.
The Order Status State Machine
Every order in your marketplace travels through a defined sequence of states. Each state transition is a one-way door — you can’t move backward (except via dispute/cancellation paths). Enforce this by checking the current status in every status-changing workflow before allowing the transition.
Search & Discovery: The Engine of Marketplace Revenue
Search is the most trafficked page in any marketplace. It is where buyers find sellers, and where sellers compete for visibility. Poor search performance — slow loading, inaccurate results, no filtering — kills conversion. Bubble’s native search has constraints you must architect around to deliver a usable search experience.
Bubble’s Search Constraints & How to Work Around Them
Keyword Search: The Correct Bubble Pattern
Bubble’s native Search for [Type] constraint only supports exact-match on text fields, not full-text search. To support keyword search (the most important buyer feature), you have two options: use Bubble’s built-in “contains keyword” (acceptable for small catalogues) or integrate Algolia for production-grade relevance at scale.
Building the Search & Filter Experience
Never trigger a search on every keystroke. Use a 300ms debounce: store the input value in a custom state, and only update the search state (which triggers the repeating group refresh) after the user stops typing for 300ms. Without debounce, every character typed fires a database query.
Each filter (category, price range, delivery time, rating) updates a custom state on the page. The repeating group data source uses these custom states as search constraints. Never “reset and re-run” the search manually — let the data source expression handle dynamic constraints.
Each listing card in search results should show: main image, title, seller name + avatar, average rating + review count, price, and delivery time. Load lazily where possible. Use a fixed cell height repeating group (not auto-height) for smoother scrolling. Avoid nested searches inside each cell — use the data passed from the parent search.
Stripe Connect: The Only Correct Way to Handle Marketplace Payments
This is the most critical technical decision in your entire marketplace build. Standard Stripe (Checkout, Payment Links) is for one-party payments: customer pays you. Marketplaces require three-party payments: customer pays you, you pay the seller minus your commission. This requires Stripe Connect — a completely different product with a different API, different onboarding flow, and different compliance requirements.
Using standard Stripe for marketplace payments is not just technically wrong — it may be legally non-compliant in your jurisdiction (as you would be holding funds on behalf of third parties without a money transmitter licence). Stripe Connect is specifically licensed for marketplace fund flows.
The Two-Phase Payment Model (Escrow)
Seller Onboarding: Stripe Connect Express
Before a seller can receive payouts, they must complete Stripe’s identity verification flow. Use Stripe Connect Express — it provides a hosted, Stripe-managed onboarding UI that handles KYC (Know Your Customer), bank account collection, and compliance. You create the account, Stripe handles verification.
Commission Models: How Marketplaces Make Money
Percentage Commission (Most Common)
Platform takes a percentage of every transaction. Example: 10–20%. Calculated as order_amount × commission_rate and passed as application_fee_amount in the PaymentIntent. Stripe automatically retains this amount when routing funds to the seller.
Flat Fee per Transaction
Fixed dollar amount per order regardless of order size. Better for high-value orders where percentage would be too punitive. Set a fixed platform_fee_cents value. Can be combined with a small percentage.
Subscription + Commission
Sellers pay a monthly subscription (managed via standard Stripe Subscriptions) plus a reduced commission rate. Two separate Stripe products working in parallel. Higher seller LTV, lower per-transaction friction.
Listing Fees (Optional)
Charge sellers to post listings above a free tier. A one-time PaymentIntent per listing publish action. Store a paid_listing flag and only set status to Active after payment confirmation via webhook.
Stripe Webhook Handlers for Marketplaces
Privacy Rules: Access Control for a Marketplace
Marketplace privacy rules differ from SaaS in one key way: some data is public (listings are visible to everyone including non-logged-in users) and some data is strictly private (order messages can only be seen by the two parties involved in that order). You need both public and private access patterns, correctly separated.
| Data Type | Privacy Condition | View | Edit | Delete | Search |
|---|---|---|---|---|---|
| Listing | Rule 1: status=Active → Everyone. Rule 2: seller = Current User → all statuses | ✓ | Seller only (Rule 2) | Seller + Admin | ✓ |
| Order | Current User = Order’s buyer OR Current User = Order’s seller | ✓ | Via workflows only | ✗ | ✓ |
| Message | Current User = Message’s order’s buyer OR Message’s order’s seller | ✓ | ✗ | ✗ | ✓ |
| Review | Rule 1: is_public=yes → Everyone (view only). Rule 2: reviewer = Current User | ✓ | Reviewer within 24h | ✗ | ✓ |
| Seller Profile | Rule 1: Everyone (public). Rule 2: User = Current User (edit own) | ✓ | Own profile only | ✗ | ✓ |
| Dispute | Current User = Order’s buyer OR Order’s seller; Admin always | ✓ | Admin only (resolution) | ✗ | ✓ |
| User | Rule 1: display_name, avatar, avg_rating → Everyone. Rule 2: all fields → Current User self | Limited (public fields) | Self only | ✗ | ✓ |
| Category | is_active = yes → Everyone | ✓ | ✗ | ✗ | ✓ |
Hide Financial Fields from Privacy Rule “View”
Even when a user has view access to an Order (as buyer or seller), some fields must be hidden from the non-owning party. The seller should never see the buyer’s stripe_customer_id, and the buyer should never see the seller’s stripe_account_id or seller_payout_cents. Use field-level privacy within the same rule by toggling individual field visibility rather than granting blanket “all fields” access.
Order-Scoped Messaging & Notifications
Every message in a marketplace must be scoped to an Order, not to a user pair or a listing. This is non-negotiable. Order-scoped messaging preserves the complete communication history for each transaction, enabling dispute resolution to see exactly what was said between buyer and seller for that specific order. It also prevents buyers and sellers from creating “shadow” message threads outside of order context that would allow off-platform transactions.
Messaging Architecture
System Messages: Automating Order Status Communication
Every order status change should automatically insert a system message into the order thread. This keeps the complete order history in one place and makes the timeline auditable. System messages use the is_system_message = yes flag and are displayed differently in the UI (no avatar, centred, timestamp-only).
Reviews, Ratings & Trust Signals
Trust is the currency of any marketplace. Buyers take risk when they pay before receiving a service. Reviews, ratings, seller verification, and response time metrics are the mechanisms that reduce perceived risk and drive conversion. Getting the review system correct — bidirectional, order-gated, tamper-proof — is essential for marketplace health.
Bidirectional Review System
Trust Signals That Drive Conversion
Verified Seller Badge
Awarded after Stripe Connect KYC is completed (payouts_enabled = true). Display a checkmark badge on all listing cards and the seller profile. This is the single most effective trust signal for buyers.
Response Time Display
Track message response time per seller. Recalculate avg_response_time_hrs on every first response to a new order. Display as “Typically responds within 4 hours” on listing and profile pages.
Top Seller Program
Award “Top Seller” status when a seller hits thresholds: e.g., 50+ completed orders, 4.8+ avg rating, 95%+ on-time delivery, 0 disputes in 6 months. Display prominently in search results.
Member Since Date
Display how long a user has been on the platform. Older accounts signal stability and reduce perceived risk. Shows on seller profile and listing cards. Simple but meaningful to buyers.
Repeat Buyer Rate
Show sellers what percentage of their buyers return. Track on Seller Profile as repeat_buyer_rate. A high repeat rate is the strongest possible signal of buyer satisfaction and product quality.
Buyer Protection Badge
Display “Protected by [Platform] Guarantee” on every listing and checkout page. Link to your dispute resolution policy. This reduces buyer anxiety significantly and has been shown to increase checkout completion rates.
Dual Onboarding: Buyers & Sellers
A marketplace has two distinct user activation paths that require different onboarding flows. A buyer is activated when they place their first order. A seller is activated when they publish their first listing and have their Stripe Connect account verified. Both paths need careful design — especially the seller path, which involves a third-party (Stripe) KYC step that many users will abandon if not guided correctly.
Buyer Onboarding Flow
Seller Onboarding Flow
Creating a Listing: The Multi-Step Form
The listing title is the most important SEO element in your marketplace. Guide sellers: “I will [service/product description] for [audience/use case].” Category selection should use a two-level hierarchy (parent → sub-category). Description field should support rich text or at minimum line breaks. Save as draft on every step with an auto-save pattern.
For service marketplaces, offer three package tiers (Basic / Standard / Premium) with different deliverables, prices, and delivery times. For product marketplaces, a single price with optional quantity pricing. Delivery time and revision count are key differentiators that buyers filter on.
The gallery is the highest-impact conversion element on a listing page. Require at least one image before publishing. Guide sellers: first image is the thumbnail in search results — it must be a professional, high-contrast visual. Support up to 10 images and one video. Store as a list of images on the Listing record.
Show a complete preview of the listing before publishing. Run validation: all required fields completed, at least one image, Stripe payouts enabled. On publish, change status from Draft to Active (or Pending Review if you run manual moderation). Trigger a “Listing Published!” celebration moment.
Production Launch Checklist & Security Hardening
A marketplace has more attack surface than a SaaS product because it handles real money flowing between real people. Every item in this checklist represents a failure mode we’ve seen in production marketplace builds. Do not launch until every item is checked.
💰 Payment & Financial Integrity
- ✓Using Stripe Connect (not standard Stripe) for all buyer-to-seller payment flows
- ✓Stripe webhook signatures validated on every event before processing
- ✓Order completion does NOT release funds via client-side workflow — only via server-side API Workflow triggered by business logic
- ✓Commission calculated server-side, not passed from client (can be manipulated)
- ✓All monetary values stored in cents (integers), never floats
- ✓Duplicate order prevention: check for existing pending order on same listing from same buyer before creating a new one
- ⚠Tested the full refund path: cancelled order → PaymentIntent cancelled → buyer card never charged
- ⚠Seller cannot trigger their own payout — release only via buyer accept OR auto-completion workflow, never via seller action
🔒 Data Privacy & Access Control
- ✓Order messages only visible to buyer and seller of that specific order — tested with three-user scenario
- ✓Buyer’s Stripe customer ID is not visible to sellers via privacy rules
- ✓Seller’s Stripe account ID is not visible to buyers via privacy rules
- ✓User email addresses never exposed via any search result or profile page
- ✓Dispute records only visible to the order’s buyer, seller, and admin users
- ✓Draft listings not visible to anyone except the owning seller
- ⚠Admin panel accessible only to users with is_admin = yes — protected by privacy rules AND page redirect on load
✉ Messaging & Communication
- ✓All communication between buyers and sellers happens inside the platform — no ability to share external contact info in the first order message
- ✓File attachments in messages are only accessible to order participants
- ✓Email notifications sent for every message received when recipient is offline
- ✓Auto-completion workflow (3-day window after delivery) tested and running correctly via Bubble’s scheduled API workflows
⭐ Trust & Quality
- ✓Reviews only creatable after Order status = COMPLETED — checked in workflow AND privacy rule
- ✓Duplicate review prevention: one review per user per order (checked before creation)
- ✓Seller avg_rating is recalculated (denormalised) on every new review — not computed live on page load
- ✓Listing moderation workflow exists: admin can deactivate any listing without deleting it
- ✓User suspension workflow: admin can disable login, hide all listings, and freeze pending payouts
⚡ Performance & Scale
- ✓Search page uses database-level constraints only — zero use of :filtered by on search results
- ✓Listing search tested with 1,000+ active listings — results appear in under 1.5s
- ✓Seller dashboard tested with 200+ orders — no timeout or slow load
- ✓All monetary denormalised counters (total_sales, total_orders) updated on event, not recalculated on load
- ✓Order messaging tested with 100+ messages per thread — pagination implemented
- ⚠Bubble app on at least Growth plan — marketplace workloads require dedicated server capacity
Recommended Bubble Plugins & Integrations for Marketplaces
| Plugin / Tool | Use Case | Notes |
|---|---|---|
| Stripe.js by Zeroqode | Stripe Connect Express onboarding, payment element UI, Customer Portal | Handles the Stripe.js SDK calls that the raw API Connector cannot |
| API Connector (built-in) | All Stripe Connect API calls, webhook payload parsing, Algolia queries | Essential for PaymentIntent create/capture/cancel, Transfer, Refund calls |
| Algolia Search plugin | Full-text listing search with relevance ranking, faceted filters | Required for marketplaces with 5,000+ listings. Dramatically better UX than Bubble native search. |
| Pusher / Ably plugin | Real-time messaging updates without page refresh | Buyers and sellers expect instant message delivery — polling is insufficient for a good inbox UX |
| SendGrid / Postmark | Transactional emails: order notifications, message alerts, payout confirmations | Postmark preferred for deliverability on order and payment emails |
| Google Maps plugin | Location-based listings (rental marketplaces, local service marketplaces) | Required for any marketplace where geography affects matching — adds address field to Listing |
| Filestack or Uploadcare | Gallery image uploads with resize, crop, and CDN delivery | Bubble’s native file upload stores raw files. Use a CDN service for listing images to improve load time. |
| Intercom plugin | In-app support chat, user identity, NPS surveys | Identify users with user_id, is_seller, total_orders for segmented support |
| Mixpanel / Segment | GMV tracking, conversion funnels, search-to-purchase analytics | Track: search performed, listing viewed, checkout started, order placed, order completed as core funnel events |
Build Your Marketplace the Right Way
Data model design, Stripe Connect integration, search architecture, and full marketplace builds —
the same disciplined approach applied to every Bubble product we ship.