API Reference

Getting started

Integration guide for VTEX or external Marketplaces and Sellers

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.

Understanding the marketplace architecture

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).

{"base64":"  ","img":{"width":1000,"height":400,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":33173,"url":""}}

  • 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.

Configuring VTEX Marketplace

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:

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.

  • 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.

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 and for VTEX sellers, follow the steps below.

Marketplace: Adding a seller to the Seller Portal

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.

{"base64":"  ","img":{"width":3751,"height":2501,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":143193,"url":""}}

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.

Sellers: Configuring your Seller Portal environment

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).

Marketplace: Adding and configuring a seller's account to VTEX Commerce

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.

Configuring seller's commission

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

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

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

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

Sellers: Sending Suggestions

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.

Marketplace: Deleting Suggestions

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

3. Marketplace: Cataloging offers

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.


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

4. Managing Catalog

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.

For Marketplaces

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



For Sellers

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.

5. Sellers: Offer Management

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.

Photo of the contributor
+ 1 contributors
Was this helpful?
Suggest edits (Github)
Photo of the contributor
+ 1 contributors
On this page