Help us improve our documentation! Tell us about your experience with this article by filling out this form.

We define marketplace as the environment where sellers expose their products and also where consumers make purchases and pay for an order. Sellers in turn are commonly the owners of the products and responsible for delivering the products to shoppers. Because VTEX promotes digital collaboration in different settings, in addition to selling their products in other marketplaces, sellers can become marketplaces themselves. Learn more about partners and growth opportunities in Marketplace Strategies at VTEX.

The architecture of a VTEX store allows merchants to become marketplaces or sellers in other VTEX stores without the need for any additional development, that is, every VTEX store is a seller in its own marketplace environment and can also be a seller in other environments like VTEX marketplaces (native marketplaces) or external (certified marketplaces or partners).

• VTEX Marketplace: Store environment hosted on the VTEX platform responsible for product sales, checkout, and payment.
• External Marketplace: Showcase store hosted on platforms external to VTEX and responsible for product sales, checkout, and payment.
• VTEX Seller: Store hosted on the VTEX platform that owns the products and is usually responsible for fulfilling orders to the consumer.
• External Seller: Store hosted on another platform, or that is not yet hosted on any platform, which owns the products and is usually responsible for fulfilling orders to the consumer. A VTEX marketplace may be interested in integrating with this external store, in order to offer its products.

To operate as a marketplace, it is necessary to configure your store according to the steps described in Configuring VTEX Marketplace.

The actions that can be performed via API are the following:

• Adding seller
• Configuring seller selection at checkout
• Configure storefront
• Configure payments

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.

• 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.
• External marketplace protocol: If you are an external marketplace that wants to integrate with a VTEX seller, see External Marketplace Integration Guide to learn how to develop a custom connector to integrate with the architecture and catalog of VTEX 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 and for VTEX sellers, follow the steps below.

The Seller Portal is an edition of the VTEX platform with essential functionalities available, so that external or VTEX sellers can quickly integrate into VTEX marketplaces.

The Seller Portal has default version developed by VTEX and if the marketplace wants its own customized version, it can develop from the VTEX version following the Seller Portal Edition App guide.

To integrate a partner's products to your marketplace using the Seller Portal as a solution, there is a flow of actions to be performed by marketplace and seller, see the image below.

The marketplace is responsible for onboarding new sellers. In other words, it is the role of the marketplace to support the seller's experience in the Seller Portal. For information about seller actions, see Seller Portal: First Steps for the Seller.

To invite and activate sellers, the marketplace must follow the endpoints listed below in the order represented. For the action of approving offers, see the section Cataloging offers.

1. POST - Invite Seller Lead
2. PUT - Accept Seller Lead
3. PUT - Create Seller from Lead

In the same category of Seller invite, you will also find the endpoints:

• GET - List Seller Leads: Returns a list of all sellers that have been invited by the marketplace.
• GET - Get Seller Lead's Data by Id: Marketplace gets a list of the sellers invited to its own environment.
• PUT - Resend Seller Lead Invite: Marketplace resends the invitation to the desired seller.
• DELETE - Delete Seller Lead: Allows the marketplace to delete a seller previously invited to its environment, if the seller has not yet accepted the invitation.

To learn how to configure your brand new Seller Portal environment and other seller actions, see Seller Portal: First Steps for the Seller. To integrate with your ERP, check out our ERP integration guide.

Catalog integration must be done manually through the Seller Portal interface or massively through REST API, using Catalog API - Seller Portal. It is not possible to integrate Catalog via spreadsheet nor via SOAP API (Webservice).

To add and configure a registered seller account and update accounts that are not hosted on the Seller Portal, the marketplace will use the following endpoints.

• POST - Configure Seller Account: Configure a specific seller's account, ultimately adding a seller to a marketplace's environment.
• PATCH - Update Seller by Seller ID: for when the marketplace needs to make updates to the settings of a specific seller.
• PUT - Upsert Sales Channel Mapping: when the seller has two affiliates pointing to the same marketplace, the account settings will be done through this endpoint.

After configuring the account, the marketplace will be able to verify the settings made.

• GET - List Sellers: Retrieve a list of sellers registered in the marketplace, and this list can be filtered by the configured trade policy.
• GET - Get Seller data by ID: Retrieve information on a specific seller, it is also possible to filter by trade policy.
• GET - Get Sales Channel Mapping Data: Retrieve information about mapping between your sales channels and a specific seller.

The marketplace will configure the seller's commissions after the initial configurations. To perform this action, one of the following endpoints can be used.

• PUT - Upsert Seller Commissions in Bulk: To apply the same commission rule to all categories of a seller already registered in the marketplace.
• PUT - Upsert Seller Commissions by Category ID: To apply a commission rule to only one category of the respective seller.

The query and management of applied commission rules will be performed through the following endpoints.

• GET - List Seller Commissions by seller ID: Retrieve the list of commissions defined for a seller.
• GET- Get Seller Commissions by Category ID: Retrieve the commission list defined for a specific category of a specific seller.
• DELETE - Remove Seller Commission by Category ID: Removes a previously defined commission for a category of a seller.

When completing the steps listed above, the marketplace will have completed the integration of a seller into its store.

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 page of VTEX Admin.

When the seller wants to suggest that one of their SKUs be sold on the marketplace, we say that the seller is sending a suggestion.
Before sending suggestions, the seller can check if the SKU already exists in the marketplace. If it does not exist, the Get SKU bindings by SKU ID call should be made after sending the suggestion to notify the marketplace that the SKU in question is a new suggestion.

• GET - Get SKU Bindings by SKU ID
• PUT - Send SKU Suggestion

If the marketplace wants to remove a submitted suggestion, they should use this call to delete the suggestion of a specific SKU.

• DELETE - Delete SKU Suggestion

When the seller sends a product suggestion to the marketplace with configured price and inventory information, after approval by the marketplace, this suggestion becomes an offer. However, before approving a seller's suggestion, it is important to ensure that the product information sent corresponds to the business strategy of the marketplace. When cataloging offers, consider the quality of information sent by the seller, such as price, product description and image.

Cataloging can be performed manually or automatically by VTEX Matcher and/or by external matchers. VTEX Matcher is a default tool used by marketplaces to analyze offers submitted by sellers and accelerate their cataloging process.

When matching received suggestions, the marketplace can perform this action either in bulk or individually.

• PUT - Match Received SKUs individually
• PUT - Match Multiple Received SKUs

Received SKUs will be approved automatically, regardless of their Matcher score, if the autoApprove feature is activated.

• PUT - Activate autoApprove in the Marketplace's Account: Will be used by the marketplace to activate the autoApprove feature with the default parameters for all received SKU modules, so that all sent SKUs are automatically approved.
• GET - Get Account's Approval Settings: After activating the autoApprove feature, the marketplace can use this endpoint to check the current settings of automatic approval acting in its store.
• PUT - Save Account's Approval Settings: Updates the VTEX Matcher's approval parameters in the Received SKU page.
• GET - Get autoApprove Status in Account Settings: Checks the autoApprove's status for a specific seller.
• PUT - Activate autoApprove Settings: The marketplace will use this to activate the autoApprove with the default parameters for a specific seller identified by sellerId.
• GET - Get Seller's Approval Settings: Checks the current automatic approval configuration for a specific seller identified by sellerId.
• PUT - Save Seller's Approval Settings: Updates the matcher's approval parameters for a specific seller identified by sellerId.

There are several actions that a marketplace or a VTEX seller can perform in catalog management. In the following sections, you will find the main actions for a marketplace and a seller.

The following endpoints will be used by the marketplace to query information about sellers in a store.

Suggestions

• GET - Get all SKU Suggestions: Retrieves information about all suggestions sent by a seller.
• GET - Get SKU Suggestion by ID: Retrieves the matcher status and score information of a specific suggestion.

Versions

• GET - Get all Versions: Retrieves information about the versions of a suggestion sent by the seller.
• GET - Get Version by ID: Retrieves information about a specific version of the suggestion.
• GET - Get Matched Offers List: Retrieves the available offers in the marketplace.
• GET - Get Matched Offer's Data by SKU ID: Retrieves the list of offers available for a specific SKU ID in the marketplace catalog.
• GET - Get Matched Offer's Data by Product ID: Retrieves a list of all offers available for a specific product ID in the marketplace catalog.

The endpoints presented will be used by sellers already connected to a marketplace to notify external marketplaces or VTEX whenever there is a price or inventory update to their SKUs.

• POST - Notify Marketplace of Price Update
• POST - Notify Marketplace of Inventory Update

Offer Management is the VTEX feature that provides sellers with more visibility into the process of sending a product to external channels, such as marketplaces. Offer Management helps sellers identify updates and resolve errors in their offers during the sending process, ensuring that they can be sent to the marketplace and synchronized correctly.

Check our Offer Management Integration Guide for more details.