API Reference

Integration Guides
External Marketplace
Get product list for an initial load

The initial load of products only occurs after the user installs and configures the connector to use the VTEX Catalog and communicate with the marketplace. All products active on the main account and associated to a sales channel must be sent to the marketplace.

{"base64":"  ","img":{"width":5262,"height":1295,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":202776,"url":""}}

Send initial load of products

Follow the steps below, to send the initial load of products in the integration’s flow:

  1. Connector validates the VTEX <> Marketplace authentication. In case it has expired, perform the update routine defined in the marketplace’s documentation. Otherwise, connectors should log the error AND put the VTEX notification in a contingency queue.
  2. VTEX Seller informs connector the sales channel’s ID for the integration.
  3. Connector collects the list of SKUs through the Get SKU by sales channel (api/catalog_system/pvt/sku/stockkeepingunitidsbysaleschannel) endpoint.
  4. For each SKU retrieved, the connector must: a. Collect details of each SKU through the Get SKU and Context endpoint. b. Validate if the SKU is active through the isActive property. c. Validate if the SKU is associated to the sales channel used in the intgration through the salesChannel property. d. Validate if the product is active through the Get Product by ID endpoint, through the isActive property. This step is optional, since the Get SKU and Context endpoint already delivers the attribute IsProductActive for this purpose. e. Identify whether the SKU conforms to the marketplace’s product registration rules. f. Validate if the product’s category is mapped in the marketplace. In case it is not mapped, the marketplace should put the SKU in the approval queue, until the mapping is complete. g. For SKUs sent with price and inventory levels set up, the connector should validate whether the SKU has price and inventory levels with the sales channel configured for the integration. This should be done through the Fulfillment Simulation endpoint, without the Postal Code. h. Collect:
    • Inventory level on all available warehouses, through the logisticsStockBalance field.
    • Sales price value with applied promotions and discounts, through the price field. It is also possible to retrieve the original price through the listPrice field.

If all validations pass, the product or SKU is sent to the marketplace and the operation is logged according to information described in the Logs made available for users.

If the IDs between VTEX and the marketplace differ, the connector should store both values. This information will be used for SKU update operations.

Be mindful to make all validations at once, and before the SKU’s publication in the marketplace’s catalog. In case there’s an error detected, the connector presents the seller a list of actions to correct. This way we can avoid the correct - publish - correct cycle.

If products do not apply to steps a, b and c, an error log must be filed, and the connector should collect the next items on the list obtained by step 2.


To avoid processing gaps due to the big volume of information of the initial load of products, we recommend:

  • Using an async messaging architecture, using individual queues by context and store.
  • Creating mechanisms that respect the marketplace API limit rates. We suggest the standard use of the Circuit Breaker integration.
  • In case any of the steps listed above presents failures in communication, we suggest using the contingency mechanism of deadLetters.
  • Being TotalReader: whenever possible, in the data transformation process, using standard values accepted by the marketplace, in case the information is not filled or sent by VTEX.
  • In case the marketplace’s processing is in lots - meaning that the connector assembles a group of SKUs, guaranteeing the the limit of records per lot is respected, according to marketplace riles, and sending them to the marketplace at once - it is fundamental to control the lot’s processing, to avoid sending SKU updates without making sure that the product exists in the marketplace.
  • Keeping a states table to know which SKUs have not been integrated with success, attempt date and the response received. This allows the system to use the contingency flow effectively, avoiding infinite loops, and avoiding reaching the request limit.

API Reference

Use the endpoints described below to get SKU, price and inventory details. It is important to note that when consuming this API, the connector must have a valid VTEX App Key and App Token. You can also download our Postman collection to access the API. The diagram illustrates the endpoints used in the integration:

{"base64":"  ","img":{"width":12866,"height":8568,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":2399698,"url":""}}
Get list of SKUs associated with a sales channel

Get details of an SKU associated with a sales channel

Check if product is active

Simulate price and inventory levels

Scenario 1: First load of products after integration’s activation

After configuring the communication with the marketplace, connectors must send the first load of products. For every product retrieved from the SKU list associated with the sales channel, the connector must:

  1. Validate category mapping.
  2. Collect skuId ‘s available in the sales channel associated with the marketplace.
  3. Get SKU information, like weight and dimensions.
  4. Use the Orderform simulation to get price and inventory level, if needed.

In case there’s any failures in an item, connectors should log the error, and move on to the next item on the list, until all SKUs are processed.

Scenario 2: Deactivate products if the integration is deactivated

If the integration’s deactivation is confirmed with the marketplace, connectors must deactivate products published in the marketplace.

  1. Get SKU information.
  2. Send SKU block or deactivation request.
  3. Exclude SKUs and clean state control of the integration’s SKUs.

Make sure that all steps are logged as either success or failure, to offer the operation’s full traceability. Check out the Logs made available for users page to learn more.

What VTEX needs to validate the integration flow

To consider the integration validated by VTEX, the connector should:

  1. Follow the step by step of the catalog integration flow.
  2. Create a table with VTEX and marketplace field mapping. It should include limitations, transformations, and required fields.
  3. Create a table that explicits which data is mandatory and which is recommended when registering products or SKUs and to improve the offer’s positioning in the marketplace’s storefront.
  4. Create a table with known error logs and actions that the user can do to solve the problem.

Template table for field mapping

VTEX fieldHow to fill it in VTEXVTEX APIMarketplace field
NameCatalog page/api/catalog/pvt/stockkeepingunitShortName
ImageCatalog page (SKU)Images
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 3 contributors
Was this helpful?
Suggest edits (Github)
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 3 contributors
On this page