VTEX marketplace: architecture, seller onboarding & build guide
Contents
Most mid-market operators underestimate VTEX marketplace until they hit the first architectural fork: should seller onboarding be UI-driven or API-driven, and does that choice lock you into a specific commission model? Get it wrong and you're retrofitting payment-split logic six months into the build.
This guide maps VTEX's two-sided marketplace model end-to-end, from the operator/seller data flow through offer suggestion lifecycle, fulfillmentSellerId behavior, and commission override mechanics, so your engineering and product teams can scope the work with accurate assumptions before a single line of code is written.
TL;DR: What to know before scoping a VTEX marketplace build
VTEX marketplace builds fail most often at two configuration points, not at the architecture level. The fulfillmentSellerId is set incorrectly when sellers source SKUs across accounts, and autoApprove rules are left at defaults that either block every offer or approve catalog data that breaks the customer experience. Get those two knobs right before anything else, as proper configuration is essential for a successful setup.
In projects we have scoped and built on VTEX, our team has configured seller onboarding pipelines, category-level commission overrides, and split-payment rules across retail and B2B marketplace engagements, giving us direct data on where engineering effort concentrates. The VTEX platform architecture supports the full multi-vendor model natively, but the gap between a working demo and a production-ready marketplace operator setup is wider than most scoping documents acknowledge.
Fast facts before you scope:
- Seller Portal is the hosted workspace where sellers configure products, pricing, inventory, logistics, and payments, it can be driven via VTEX Admin UI or entirely via REST API for custom onboarding flows.
- split-payment processing calculates commissions automatically at checkout; VTEX supports percentage, fixed-fee, tiered, and category-specific commission structures per seller.
- autoApprove rules control whether offer suggestions go live immediately or enter a manual review queue, leaving this misconfigured is the single fastest way to corrupt your catalog.
- fulfillmentSellerId identifies who physically fulfills each order; critical when a seller sells SKUs sourced from a different seller account.
- Billing is revenue-share, not a flat monthly fee, non-VTEX sellers have a different take-rate structure than VTEX-native sellers, an asymmetry that affects your commercial model.
This guide covers VTEX marketplace architecture, the seller onboarding sequence (UI and API paths), commission configuration, split-payment mechanics, and the seller-fulfilled vs. marketplace-fulfilled logistics decision, the concrete layer you need to scope the build accurately.
How VTEX marketplace architecture works: The two-sided model
The marketplace operator account is the structural center of every VTEX Commerce Platform deployment: it owns the catalog definition, the checkout flow, and the payment split logic. Sellers write offers against that catalog, they never own the product record itself. That distinction matters more than it sounds, and it shapes every integration decision downstream.
To learn how the account hierarchy works, consider the following structure. The marketplace operator holds one or more sales channel configurations, each of which can expose a different catalog subset, pricing rule, or storefront. External sellers connect to a specific sales channel, not to the marketplace account directly.
When a seller sends an offer: a price, stock quantity, and logistics commitment attached to an existing SKU, that offer travels through the offer suggestion management pipeline before it becomes purchasable. Nothing a seller writes touches the canonical product data until the marketplace approves it.
Data flows in one direction at offer creation and in the opposite direction at order fulfillment. Seller writes offer → marketplace evaluates and approves → offer becomes live on the storefront → customer places order → order fans out to the relevant seller account via VTEX's order management routing. The fulfillmentSellerId field on the order line identifies who actually ships the item, which diverges from the selling account whenever a seller sources inventory from another seller's stock or when the marketplace takes over fulfillment itself.
Seller-fulfilled is VTEX's default assumption: sellers manage their own shipping strategy, carrier contracts, and SLA definitions inside the Seller Portal. Marketplace-fulfilled flips that: the operator's logistics network handles physical dispatch, and sellers simply confirm stock availability. Most mid-market builds we have scoped start seller-fulfilled for simplicity, then add marketplace-fulfilled lanes for high-volume or strategically important seller categories where the operator wants tighter SLA control.
For external seller integration, meaning sellers not already on the VTEX platform, the architectural surface area is larger. Their systems must connect via REST APIs to sync inventory, receive order notifications, and confirm shipment events. VTEX's marketplace integration documentation defines the full protocol. Non-VTEX sellers also face an asymmetric billing arrangement: the platform's take rate is charged only to the marketplace operator, not split with the seller, unlike the treatment for VTEX-native sellers where both sides share the cost. That asymmetry affects how operators structure their commercial terms with external partners.
For the broader VTEX account architecture and how the platform handles multi-tenant SaaS topology, our VTEX platform guide covers the context. Catalog and product data mechanics, particularly relevant when sellers need clean, normalized product information before their offers can match SKUs, are in the PIM and VTEX integration guide.
Seller onboarding workflow: Invite to first live order
The VTEX Seller Portal onboarding workflow runs seven discrete stages from first contact to live order. Each stage has a clear owner, marketplace operator or seller, and a defined API endpoint if you want to bypass the UI entirely.
Stage 1, Invite. The marketplace operator sends an invitation to the seller's email address via VTEX Admin or the `POST /api/seller-register/pvt/sellers` endpoint (VTEX Help Center - Seller Portal: Getting started for the marketplace). For high-volume onboarding programs, use the API path. Our team has scripted bulk invitations for clients bringing 200+ sellers onto a new marketplace in a single launch window, a task that would have taken weeks via the UI.
Stage 2, Accept. The seller receives the email, creates or links their VTEX account, and accepts terms. Non-VTEX sellers (those without an existing VTEX store) complete a full account creation here: this is where the UI vs. API path diverges most sharply. A marketplace wanting a white-labeled onboarding experience can create the Seller Portal account on the seller's behalf via API, then pass credentials directly.
Stage 3, Activate. The marketplace operator activates the seller account. Until activation fires, the seller cannot configure anything. Activation also sets the seller's fulfillmentSellerId, the identifier that will tag every order line this seller fulfills, which matters when a seller sources SKUs from a third party.
Stage 4, Configure. The seller sets up pricing rules, inventory feeds, logistics (seller-fulfilled vs. marketplace-fulfilled), and payment information inside the Seller Portal. In projects we have scoped for fashion and electronics verticals, this stage consistently takes the longest, typically five to ten business days for sellers without a pre-built product feed. Clean catalog data matters here; see our VTEX PIM integration guide for the upstream data requirements.
Stage 5, Offer submission. Sellers submit offers against the marketplace's catalog using the offer suggestion management interface or the `POST /api/offer-manager/pvt/seller/{sellerId}/offer` endpoint. An offer maps a seller SKU to a marketplace catalog record, with price and inventory attached. The offer suggestion lifecycle has three states: pending, approved, and refused, and the marketplace operator controls the transition.
Stage 6, Offer approval. Here is where autoApprove rules determine operational load. When autoApprove is enabled at the account or category level, offers matching pre-defined criteria clear automatically, no manual review. In practice, our team has configured autoApprove for commodity categories (consumables, accessories) while leaving it off for high-value or regulated categories (electronics, supplements), where a human review step catches pricing anomalies before they reach the customer.
Stage 7, First live order. Once at least one offer is approved, the seller is live. The marketplace routes order lines to the seller, split-payment processing allocates the contracted commission, and the seller manages fulfillment from the Seller Portal order management view.
API vs. UI: the UI path works for marketplaces onboarding sellers one at a time with operational staff available; the API path is mandatory when you need custom branding, bulk onboarding, or programmatic autoApprove logic tied to your own seller scoring data.
UI-based vs. API-driven onboarding: When each path makes sense
API-driven external seller integration scales; VTEX Seller Portal UI onboarding gets your first sellers live faster. Choose based on seller volume and how much control you need over the registration experience.
UI-based onboarding (VTEX Admin + Seller Portal) works well when you're launching with a curated set of sellers, say, under 50, and your team wants to configure each account manually, review catalog submissions through the built-in offer management interface, and avoid building custom middleware. The Seller Portal guides sellers through product data entry, pricing, inventory, and logistics configuration without engineering effort on the marketplace side. In projects we have scoped for mid-market retailers entering marketplace commerce, UI-driven onboarding typically gets a seller from invite to first live order in two to five business days, assuming clean product data.
API-driven onboarding makes sense once seller volume, automation requirements, or a custom registration UX pushes beyond what the Admin interface can handle. The `POST /api/seller-register/pvt/sellers` endpoint lets you create Seller Portal accounts programmatically, useful when you want to pre-populate seller information from an external CRM, trigger onboarding from your own platform UI, or build a white-labeled flow that doesn't expose VTEX branding. Our team has configured API-driven paths for marketplace operators running high-velocity seller acquisition; the engineering effort runs roughly three to six weeks depending on how much custom validation logic sits around the seller registration and offer suggestion management steps.
| UI-Based | API-Driven | |
|---|---|---|
| Best for | <50 sellers, curated launch | High-volume, automated, or white-labeled |
| Engineering effort | Near-zero | 3-6 weeks |
| Seller experience | Standard Seller Portal | Fully custom |
| Maintenance overhead | Low | Medium (API contract management) |
Offer & catalog management: Suggestions, matching, and autoApprove
Offer suggestion management in VTEX Commerce Platform follows a defined lifecycle: a seller submits an offer, the marketplace either manually reviews it or processes it automatically via autoApprove rules, and only approved offers become visible to customers. Understanding where that lifecycle can break is more useful than the happy path.
Catalog matching vs. new product creation
When a seller submits an offer for a SKU that already exists in the marketplace catalog, VTEX attempts to match it by EAN or reference ID. A matched offer inherits the marketplace's product data, title, images, description, and the seller contributes price and inventory. This is the cleanest path: the marketplace controls the customer-facing catalog, sellers compete on price and availability.
If no match exists, the seller can submit a new product suggestion. The marketplace team then reviews the incoming data, title, category mapping, images, attributes, before approving it into the catalog. In our experience scoping VTEX projects, this review queue is where catalog quality degrades fastest. Sellers submit products with missing attributes, wrong category assignments, or low-resolution images. Without a defined SLA on the review side, the queue backs up. We recommend configuring category-level required-attribute validation before offers reach the approval queue, rather than catching errors manually after the fact.
autoApprove rule logic and its risks
AutoApprove rules let the marketplace configure conditions under which offer updates, price changes, inventory updates, or new offers from trusted sellers, are accepted without manual review. Per the VTEX marketplace configuration documentation, autoApprove can be scoped to specific sellers, categories, or offer types.
Over-permissive autoApprove rules are a real operational risk. A rule that auto-approves all price updates from all sellers, for example, can surface a seller's pricing error, a decimal-place mistake that prices a €500 item at €5, directly to customers before anyone notices. In projects we have scoped, we configure autoApprove narrowly: trusted sellers only, inventory updates only, with price changes always gated behind a review step or a price-floor validation rule. The engineering effort to add that guard is small; the ops cost of a live pricing incident is not.
Commission structures: Percentage, fixed-fee, tiered & category overrides
VTEX's revenue-share billing model applies commissions automatically during split-payment processing, no separate invoicing step required. The marketplace operator configures commission rules in settings before sellers go live, and VTEX calculates the take-rate split at transaction time.
Two commission types, not one
Every seller configuration carries two independent commission fields: a product commission (percentage of the item sale price) and a shipping commission (percentage of the shipping fee charged to the customer). Both are calculated and split separately during payment settlement. Leaving the shipping commission at zero is a common oversight in initial configurations. This can cost marketplace operators meaningful revenue in high-volume, low-AOV channels where shipping fees represent a significant share of basket value, particularly for commodity goods with thin margins.
Commission models VTEX supports
| Model | How it works | Typical use case |
|---|---|---|
| Percentage | Fixed % of sale price per seller or category | Standard take-rate for most verticals |
| Fixed fee | Flat amount per transaction | Subscription-box or fixed-price commodity sellers |
| Tiered | Rate changes at revenue thresholds | Incentivizing high-volume sellers |
| Category-specific override | Different rate applied to a defined category | Fashion vs. electronics under one seller account |
Commission rules are configured per seller across all categories, or per seller per single category. In projects scoped for multi-vertical marketplace operators, this override capability consistently reduces configuration overhead when a single seller spans both high-margin and low-margin product lines, such as health and beauty goods alongside consumer electronics.
VTEX documentation does not publish a hard cap on the number of category-specific override rules configurable per seller account. If your use case involves an unusually large category taxonomy, confirm current platform limits directly with your VTEX account team before finalizing your commission architecture.
For non-VTEX sellers, the contracted take-rate is charged only to the marketplace operator. For VTEX-native sellers, it is split between seller and marketplace, a billing asymmetry worth surfacing early in commercial negotiations with sellers already using VTEX to run their own store.
Split payments in VTEX: How the payment flow actually works
Split-payment processing in VTEX Commerce Platform fires at transaction time, not post-settlement. When a customer completes checkout, VTEX calculates the marketplace's commission deduction inline and splits the net amount to the seller automatically, no separate invoicing, no manual reconciliation step.
Where the commission deduction actually fires
The split happens during payment capture, before funds are routed. VTEX reads the configured commission settings for that seller and category, deducts the marketplace take-rate, and records the net seller receivable in the same transaction record. Product commissions and shipping commissions are deducted independently, and the shipping split follows whatever shipping commission rate is configured for that seller, which may differ from the product rate.
The non-VTEX seller billing difference, frequently misunderstood
This is where many teams scope the architecture incorrectly. For VTEX-native sellers, sellers who run their own VTEX account, the contracted take-rate is charged to both the seller and the marketplace, because VTEX has a direct commercial relationship with each party. For external sellers (non-VTEX accounts onboarded via Seller Portal), the take-rate is charged only to the marketplace operator. The marketplace then enforces its own commercial terms with those sellers outside the VTEX billing layer.
In practice: if your seller mix is primarily non-VTEX businesses, independent brands, regional suppliers, dropshippers selling physical goods or service offerings across multiple channels, your VTEX Commerce Platform invoice reflects the full GMV-based fee. You carry the cost and recover it through the commission rates you configure per seller. Get those commission settings wrong and the margin gap is structural, not a rounding error.
A common failure pattern: a marketplace with a majority non-VTEX seller base leaves the shipping commission rate misaligned with actual carrier costs per seller tier, and the resulting margin shortfall gets misattributed to logistics overhead rather than traced back to commission configuration. The fix lives entirely in commission settings, with no changes needed to the payment integration layer, once the shipping commission rate is corrected per seller tier.
For teams connecting sellers programmatically via the VTEX Marketplace APIs, the split data is accessible at order level, which makes it straightforward to pipe per-seller revenue data into external BI or finance systems without needing a separate reconciliation export.
Fulfillment models: What fulfillmentSellerId controls and how to decide
The fulfillmentSellerId field identifies who physically ships an order, and getting it wrong silently routes fulfillment to the wrong party. VTEX's default architecture assumes the seller listed on the order is also the seller fulfilling it, but that assumption breaks the moment a seller sources SKUs from another seller or the marketplace operates its own warehouse.
How fulfillmentSellerId works in practice
When a seller sells a product hosted in their own inventory, fulfillmentSellerId equals that seller's account ID. When the marketplace wants to fulfill on the seller's behalf, centralizing logistics for quality control or SLA guarantees, fulfillmentSellerId is set to the marketplace's own seller ID instead. VTEX routes the pick-pack-ship instruction accordingly, while the revenue split still credits the originating seller. This is the field that makes marketplace-fulfilled dropshipping work without restructuring the catalog or order management architecture.
Choosing the right model for your context
The decision isn't binary. VTEX natively supports three patterns that can coexist across your seller mix:
| Pattern | fulfillmentSellerId points to | Best for |
|---|---|---|
| Seller-fulfilled | The individual seller | Sellers with mature 3PL or own warehouse |
| Marketplace-fulfilled | The marketplace operator | New sellers, perishables, high-return categories |
| Ship-from-store / click-and-collect | A specific store location ID | Omnichannel retail, last-mile reduction |
Dropshipping maps cleanly onto seller-fulfilled: the seller never holds stock, and the fulfillmentSellerId points to their account while they relay orders to their supplier. Ship-from-store and click-and-collect require configuring logistics settings at the seller's physical location level within the platform, not just at the account level.
A common pattern for multi-category marketplaces: apply marketplace-fulfilled status to new sellers and high-return categories (apparel, footwear) while established sellers with proven 3PL partners retain seller-fulfilled status. Define that routing logic per category early, because retrofitting it after sellers are live significantly increases coordination overhead.
VTEX vs. Mirakl vs. Marketplacer: Comparison across key dimensions
VTEX Commerce Platform, Mirakl, and Marketplacer serve the same multi-vendor use case but make fundamentally different architectural bets: and those bets determine integration cost, time-to-first-seller, and long-term operator control.
| Dimension | VTEX Commerce Platform | Mirakl | Marketplacer |
|---|---|---|---|
| Hosting model | Fully hosted SaaS; no infrastructure to manage | Hosted SaaS; typically runs alongside an existing storefront | Hosted SaaS |
| Storefront ownership | Operator owns storefront, headless or native VTEX IO | Storefront-agnostic; Mirakl is a marketplace layer bolted onto any existing commerce platform | Operator owns storefront; API-first |
| External seller integration | REST API or Seller Portal UI; non-VTEX sellers connect via the External Seller protocol | API-first operator console; sellers connect via Mirakl Connect API | API-first; sellers connect via Marketplacer Seller API |
| Commission configuration | Percentage, fixed-fee, tiered, or category-specific commission override: configured per seller or per category, calculated automatically during split-payment processing | Percentage-based with operator-defined rules; category-level overrides supported | Percentage and fixed-fee; category-level rules available |
| Split-payment processing | Native, VTEX calculates and routes payments to sellers automatically | Requires integration with external payment gateway; Mirakl Pay available as add-on | Requires external payment gateway integration |
| Seller onboarding flow | Invitation-based via Admin UI or fully API-driven for custom white-label flows | Operator-configured onboarding via Mirakl Operator Portal; less API surface for custom flows | API-driven; designed for programmatic onboarding |
| Fulfillment model | Seller-fulfilled default; marketplace-fulfilled supported; fulfillmentSellerId controls routing per order | Seller-fulfilled by default; marketplace fulfillment requires custom integration | Seller-fulfilled; marketplace fulfillment via third-party logistics integration |
| TCO profile | Revenue-share take rate on approved GMV; no flat monthly platform fee for the marketplace operator on the core product | Flat platform licensing fee plus per-transaction fees; costs scale with seller count | Subscription-based licensing; per-seller pricing tiers |
The TCO difference is structural. VTEX's billing is GMV-contingent, the marketplace operator pays more as the platform grows, but pays less before it scales. Mirakl's licensing model front-loads cost regardless of seller or transaction volume.
Where VTEX has a clear edge is the architecture: storefront, catalog management, split-payment processing, and external seller onboarding all live in one platform. Mirakl's strength is the opposite, it integrates cleanly into an existing commerce stack that the operator is unwilling to replace. If the operator already runs Salesforce Commerce Cloud or SAP Commerce and does not want to re-platform, Mirakl is the lower-disruption path.
In projects we have scoped, the decision most often comes down to a single question: does the operator want one platform to own commerce and marketplace together, or does the operator want a best-of-breed marketplace layer on top of an existing system? VTEX wins the first scenario; Mirakl wins the second. For a deeper read on VTEX's broader commerce architecture before committing to that decision, see our VTEX platform guide.
Frequently asked questions about VTEX marketplace
How long does VTEX seller onboarding typically take from invite to first live order?
Does VTEX marketplace support external sellers who don't use the VTEX platform?
Is VTEX marketplace compatible with headless or composable storefronts?
Can you set a commission cap or minimum per seller in VTEX?
How does VTEX split payment differ for VTEX-native vs. non-VTEX sellers?
Pre-build scoping checklist: Decisions to lock in before development starts
Lock these six decisions before your development team writes a single line of integration code. Reopening them mid-build costs weeks; the VTEX platform architecture makes several of them genuinely difficult to reverse.
- Seller type mix. Classify your seller population: VTEX-native accounts vs. external sellers using the Seller Portal. This determines take-rate asymmetry, non-VTEX sellers incur a take rate charged to the marketplace operator only, while VTEX-native sellers split it. Define the ratio early; it changes your revenue-share model and billing projections.
- Onboarding path: UI vs. API. The VTEX Admin UI handles standard invite-and-activate workflows. If you want to programmatically create Seller Portal accounts on behalf of sellers, common for enterprise partners or high-volume onboarding, plan the REST API path from day one. In projects we have scoped, switching from UI-driven to API-driven onboarding mid-build added three to four weeks of engineering effort.
- Commission structure and category-specific overrides. Decide whether you need flat percentage, fixed-fee, tiered, or category-specific commission override logic. VTEX calculates product commissions and shipping commissions separately during split-payment processing; configure these per seller or per single category. Leaving this undefined means developers configure a default and then retrofit exceptions under time pressure.
- Fulfillment ownership and fulfillmentSellerId. Decide the default: seller-fulfilled, marketplace-fulfilled, or a hybrid. The fulfillmentSellerId field identifies who physically ships each order, this matters immediately when sellers list SKUs sourced from other sellers. Nailing down ship-from-store, click-and-collect, and dropshipping rules before build avoids mis-mapped logistics flows in order management.
- autoApprove risk tolerance. The marketplace operator sets autoApprove rules per seller or per category to control whether offer suggestions go live without manual review. High-trust, curated sellers can have autoApprove enabled; new or external sellers typically need human review. Define the approval matrix, including escalation rules for price anomalies, before the offer suggestion management workflow is built.
- Sales channel configuration and storefront architecture. Each VTEX marketplace requires a dedicated sales channel account. Decide upfront whether you are running a single customer-facing storefront, a white-label architecture for sub-operators, or a headless front end consuming the VTEX API. This determines how catalog data, pricing, and promotions are partitioned across accounts, and it is substantially harder to restructure after sellers have connected.
For catalog and product-data decisions that feed into steps 1-6, the VTEX PIM integration guide covers the data model mechanics in detail (VTEX Back office integration guide (ERP/PIM/WMS)).
Ready to scope your VTEX marketplace build?
If the scoping checklist in the previous section surfaced decisions you haven't locked in yet, that's the right moment to bring in an engineering partner who has configured VTEX Commerce Platform for marketplace operators before, not after the first sprint.
Our team has scoped and built multi-vendor commerce projects across verticals, navigating the specifics of VTEX platform architecture: seller onboarding via API vs. UI, split-payment processing logic, and the seller-fulfilled vs. marketplace-fulfilled fulfillment call. We've seen where external seller data quality breaks catalog integrity, and where commission configuration decisions made early become expensive to change. If you're evaluating VTEX and want a straight read on architecture, timeline, and where the real engineering effort sits, Build your commerce platform.
