From 5bf7890a59b9e79dfa3ac150daefb29084a00589 Mon Sep 17 00:00:00 2001 From: Ana Barbosa Date: Fri, 29 May 2026 13:56:45 -0300 Subject: [PATCH 1/3] Update marketplace integration overview --- .../Getting-Started/marketplace-overview.md | 56 ++++++++++++++++++- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/docs/guides/Getting-Started/marketplace-overview.md b/docs/guides/Getting-Started/marketplace-overview.md index ea91148946..c89d679dec 100644 --- a/docs/guides/Getting-Started/marketplace-overview.md +++ b/docs/guides/Getting-Started/marketplace-overview.md @@ -3,10 +3,14 @@ title: "Marketplace" slug: "marketplace-overview" hidden: false createdAt: "2023-07-19T17:08:52.219Z" -updatedAt: "2023-07-19T17:08:52.219Z" +updatedAt: "2026-05-29T00:00:00.000Z" excerpt: "Integration guide for VTEX or external Marketplaces and Sellers" hidePaginationPrevious: false hidePaginationNext: false +seeAlso: + - "/docs/guides/getting-started-with-storefront-solutions" + - "/docs/guides/multilevel-omnichannel-inventory" + - "/docs/guides/orders-overview" --- >ℹ️ Help us improve our documentation! Tell us about your experience with this article by filling out [this form](https://forms.gle/fQoELRA1yfKDqmAb8). @@ -32,9 +36,30 @@ The actions that can be performed via API are the following: - [Adding seller](#1-marketplace-adding-sellers) - [Configuring seller selection at checkout](https://developers.vtex.com/docs/guides/checkout-overview) -- [Configure storefront](https://developers.vtex.com/docs/guides/getting-started-3) +- [Customizing the marketplace storefront](#customizing-the-marketplace-storefront) - [Configure payments](https://developers.vtex.com/docs/guides/payments-integration-guide) +## Customizing the marketplace storefront + +As a VTEX marketplace, your storefront is where approved seller offers are displayed and where shoppers complete checkout. After integrating sellers and cataloging offers, you can customize how products and seller information appear to customers. + +The customization approach depends on your storefront technology. See [Getting started with storefront solutions](https://developers.vtex.com/docs/guides/getting-started-with-storefront-solutions) to compare FastStore, Store Framework, and Legacy CMS Portal, including marketplace support for each option. + +### Store Framework + +- [Store Framework](https://developers.vtex.com/docs/guides/store-framework) +- [Using CSS handles for store customizations](https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization) +- [Working with Site Editor](https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor) + +### FastStore + +- [Overrides overview](https://developers.vtex.com/docs/guides/faststore/overrides-overview) +- [Using themes overview](https://developers.vtex.com/docs/guides/faststore/using-themes-overview) + +### Checkout and seller display + +To configure how sellers are selected and displayed during checkout, see [Checkout overview](https://developers.vtex.com/docs/guides/checkout-overview). + ## Integrating External Marketplaces or External Sellers The Marketplace Protocol is a set of API requests and definitions to help you integrate external sellers into a VTEX marketplace, as well as external marketplaces into VTEX sellers. @@ -42,6 +67,15 @@ The Marketplace Protocol is a set of API requests and definitions to help you in - **External seller protocol:** If you are a VTEX marketplace and want to integrate offers from an external seller into your catalog, see our [External Seller Integration Guide](https://developers.vtex.com/docs/guides/external-seller-integration-guide). - **External marketplace protocol:** If you are an external marketplace that wants to integrate with a VTEX seller, see [External Marketplace Integration Guide](https://developers.vtex.com/docs/guides/external-marketplace-integration-guide) to learn how to develop a custom connector to integrate with the architecture and catalog of VTEX sellers. +### Phase overview + +| Phase | Section | Main actors | +| --- | --- | --- | +| Seller onboarding | [1. Marketplace: Adding Sellers](#1-marketplace-adding-sellers) | Marketplace, Seller | +| Suggestions | [2. Sending and managing suggestions](#2-sending-and-managing-suggestions) | Seller | +| Cataloging | [3. Marketplace: Cataloging offers](#3-marketplace-cataloging-offers) | Marketplace | +| Ongoing sync | [4. Managing Catalog](#4-managing-catalog) | Seller, Marketplace | + ## 1. Marketplace: Adding Sellers VTEX marketplaces that want to make products from sellers available in their store must go over some processes. The first step is to find out if the seller you want to connect to is a VTEX seller or an external seller. For *external sellers*, verify the [External Seller Integration Guide](https://developers.vtex.com/docs/guides/external-seller-integration-guide) and for *VTEX sellers*, follow the steps below. @@ -106,6 +140,24 @@ The query and management of applied commission rules will be performed through t When completing the steps listed above, the marketplace will have completed the integration of a seller into its store. +## Multilevel Omnichannel Inventory (MOI) + +[Multilevel Omnichannel Inventory (MOI)](https://developers.vtex.com/docs/guides/multilevel-omnichannel-inventory) is a VTEX setting that allows franchise accounts or white label sellers' inventory to be sold in marketplaces connected to the main seller account — without integrating each franchise individually with the marketplace. + +In a three-level architecture, the marketplace (level 1) sells products fulfilled by franchise accounts or white label sellers (level 3) through a direct seller (level 2). Orders follow the [chain order flow](https://developers.vtex.com/docs/guides/orders-overview#chain-flow). + +> ⚠️ MOI is available only for integrations between VTEX marketplaces and VTEX sellers. The feature has been [discontinued for external marketplaces](https://developers.vtex.com/docs/guides/multilevel-omnichannel-inventory-api-integration). + +### Configuring MOI via API + +When adding or updating a seller, configure MOI through the [Configure Seller Account](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/seller-register/pvt/sellers) endpoint by setting the `fulfillmentEndpoint` field. See [Setup for VTEX marketplaces](https://developers.vtex.com/docs/guides/multilevel-omnichannel-inventory#setup-for-vtex-marketplaces) for the required format and parameters. + +For a complete integration guide, see: + +- [Multilevel Omnichannel Inventory](https://developers.vtex.com/docs/guides/multilevel-omnichannel-inventory) +- [Multilevel Omnichannel Inventory API integration](https://developers.vtex.com/docs/guides/multilevel-omnichannel-inventory-api-integration) +- [Integrating with the Multilevel Omnichannel Inventory](https://developers.vtex.com/docs/guides/orders-overview#integrating-with-the-multilevel-omnichannel-inventory) (Orders overview) + ## 2. Sending and managing suggestions When the seller is integrated into a marketplace, it will begin to suggest products from its catalog to the marketplace. The APIs mentioned in this section refer to the [Received SKUs](https://help.vtex.com/en/tutorial/manual-sku-cataloging--tutorials_396) page of VTEX Admin. From 5a662ddc74c2a2e249e4ba60781f16cf6cd085ec Mon Sep 17 00:00:00 2001 From: Ana Barbosa Date: Tue, 2 Jun 2026 13:52:55 -0300 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Mariana Caetano Pereira <67270558+mariana-caetano@users.noreply.github.com> --- docs/guides/Getting-Started/marketplace-overview.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/guides/Getting-Started/marketplace-overview.md b/docs/guides/Getting-Started/marketplace-overview.md index c89d679dec..2164e3220e 100644 --- a/docs/guides/Getting-Started/marketplace-overview.md +++ b/docs/guides/Getting-Started/marketplace-overview.md @@ -43,7 +43,7 @@ The actions that can be performed via API are the following: As a VTEX marketplace, your storefront is where approved seller offers are displayed and where shoppers complete checkout. After integrating sellers and cataloging offers, you can customize how products and seller information appear to customers. -The customization approach depends on your storefront technology. See [Getting started with storefront solutions](https://developers.vtex.com/docs/guides/getting-started-with-storefront-solutions) to compare FastStore, Store Framework, and Legacy CMS Portal, including marketplace support for each option. +The customization approach depends on your storefront technology. See [Getting started with storefront solutions](https://developers.vtex.com/docs/guides/getting-started-with-storefront-solutions) to compare FastStore, Store Framework, and CMS Portal (Legacy), including marketplace support for each option. ### Store Framework @@ -69,6 +69,8 @@ The Marketplace Protocol is a set of API requests and definitions to help you in ### Phase overview +After choosing the appropriate integration model, the marketplace workflow can be broken down into four main phases. + | Phase | Section | Main actors | | --- | --- | --- | | Seller onboarding | [1. Marketplace: Adding Sellers](#1-marketplace-adding-sellers) | Marketplace, Seller | From 00d49b9a655746a336e4aaa9787cc9b0b477574e Mon Sep 17 00:00:00 2001 From: Ana Barbosa Date: Tue, 2 Jun 2026 14:59:19 -0300 Subject: [PATCH 3/3] Suggested modifications applied --- .../Getting-Started/marketplace-overview.md | 45 ++++++++++++++++++- 1 file changed, 43 insertions(+), 2 deletions(-) diff --git a/docs/guides/Getting-Started/marketplace-overview.md b/docs/guides/Getting-Started/marketplace-overview.md index c89d679dec..6d95eee32b 100644 --- a/docs/guides/Getting-Started/marketplace-overview.md +++ b/docs/guides/Getting-Started/marketplace-overview.md @@ -47,18 +47,59 @@ The customization approach depends on your storefront technology. See [Getting s ### Store Framework +With Store Framework, you customize the storefront by composing blocks exported by VTEX apps in your theme. For marketplace specific use cases, see [Displaying sellers and approved offers](#displaying-sellers-and-approved-offers). + - [Store Framework](https://developers.vtex.com/docs/guides/store-framework) +- [Seller Selector](https://developers.vtex.com/docs/guides/vtex-seller-selector) - [Using CSS handles for store customizations](https://developers.vtex.com/docs/guides/vtex-io-documentation-using-css-handles-for-store-customization) - [Working with Site Editor](https://developers.vtex.com/docs/guides/store-framework-working-with-site-editor) ### FastStore +FastStore does not provide a native seller selector component. To display seller information or offers in a custom way, you can override existing components or create a new section to build the storefront content your marketplace needs. + - [Overrides overview](https://developers.vtex.com/docs/guides/faststore/overrides-overview) +- [Creating a new section](https://developers.vtex.com/docs/guides/faststore/developing-and-overriding-components-creating-a-new-section) - [Using themes overview](https://developers.vtex.com/docs/guides/faststore/using-themes-overview) -### Checkout and seller display +### Common marketplace storefront customizations + +Beyond the storefront technology guides above, there are marketplace-specific behaviors that affect what shoppers see, regardless of your storefront stack. These are driven by catalog and seller settings rather than by the theme alone, as described in the sections below. + +#### Displaying sellers and approved offers + +When more than one seller offers the same SKU, you can let shoppers compare offers and choose where to buy. In Store Framework, the [Seller Selector](https://developers.vtex.com/docs/guides/vtex-seller-selector) app renders the available sellers for a product, including price, shipping, and a buy button per seller. + +To enable it, add the `link-seller` block to your product page (`store.product`) template. It displays a link with the number of sellers for the product and opens the Seller Selector page: + +```json +"flex-layout.col#right-col": { + "props": { + "preventVerticalStretch": true, + "rowGap": 0 + }, + "children": [ + "product-name", + "link-seller", + "product-price#product-details", + "flex-layout.row#buy-button" + ] +} +``` + +Keep in mind that an approved offer is only displayed in the storefront if the seller is mapped to the [Sales channel](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV) used by that store. If an offer is approved but does not appear in the storefront, the trade policy mapping is the first thing to check. + +#### Controlling price and availability before the shopper sets a location + +During navigation stages where the store does not yet know the shopper's location (such as the home page, category pages, and shelves), the storefront cannot evaluate every seller's delivery area. In this context, VTEX shows price and availability based only on the main seller and on comprehensive sellers. + +A seller is comprehensive when its `isBetterScope` property is set to `true`, which tells VTEX that its products can be shown in navigation contexts without a defined location. This behavior also applies in the cart until the shopper informs a delivery ZIP code. + +Set a seller as comprehensive only when its delivery area is relevant to most of your customer base. If you set a seller with restricted coverage as comprehensive, shoppers may see price and availability that do not apply to their region, and they will only find out after entering the ZIP code, hurting the experience. + +#### Seller selection at checkout -To configure how sellers are selected and displayed during checkout, see [Checkout overview](https://developers.vtex.com/docs/guides/checkout-overview). +When multiple sellers offer the same SKU, the [white label seller selection algorithm](https://help.vtex.com/en/tutorial/white-label-sellers-selection-algorithm--3MemNQ4pKkWCpMdzI27AHa) determines which seller fulfills the item, considering criteria such as price and delivery conditions for the shopper's address. To configure how sellers are selected and displayed during checkout, see [Checkout overview](https://developers.vtex.com/docs/guides/checkout-overview). ## Integrating External Marketplaces or External Sellers