Check out the updated version of this marketplace integration guide in our Developer Portal.

This document assists in integrating a non-VTEX-hosted Marketplace with a VTEX-hosted Seller.

The actions required to perform this integration on the Marketplace side can be divided into two blocks:

• ** A) ** Actions regarding catalog updates (change in catalog, price or SKU inventory);

• ** B) ** Actions regarding the sending and processing of orders (cart simulation, order submission, dispatch authorization, receipt of invoice, carrier tracking and cancellation).

In this article, you get an overview of the process of integrating both blocks, as well as access to the links with the each action's specific step-by-step.

Some Concepts Seller - Product owner, responsible for fulfillment, i.e. for complying with SKU delivery.
Marketplace/Affiliate - Window display owner (where the end customer sees the product), responsible for displaying and selling the SKU.
SKU - Item to be exchanged and sold between Marketplace and Seller.
Trade Policy - Product assortment, pricing and logistics settings that determine the characteristics of a sales channel.
Endpoint - Access point for an internet service, service ready to receive a request and return a reply.
MarketplaceServicesEndpoint - Access point where VTEX Sellers give order information to the Marketplace, such as invoice and the order tracking code.

• Within the VTEX-hosted store (Seller), an affiliate (ie Marketplace) will be added, affiliate who is interested in receiving the catalog and SKU updates.

• The Marketplace must implement an endpoint where it will receive notifications about any price, inventory or catalog changes from the seller.

• In VTEX Seller, each time a SKU marketed by Marketplace undergoes a price, inventory or catalog change, the affiliate notification endpoint will be called.

• When the Marketplace is notified by the Seller that a SKU has changed, the Marketplace should check whether it currently sales that SKU.

if yes: the Marketplace uses the Catalog's API to get and save the SKU data from the Seller.
if no: the Marketplace uses the Catalog's API to get the SKU data from the Seller and then decide whether that data will be included in the store or not.

1. Marketplace receives notifications on price, inventory or catalog changes.

2. Marketplace searches for Seller's SKU data using the Catalog's API.

3. Marketplace searches for SKU price, inventory and shipping data using the Fulfillment API.

For more information, see the documentation for developers External Marketplace.

The integrations flow referring to the shipping and processing of orders can be divided into 3 stages, each with its specific actions:

• Products are either added or to the Marketplace cart or changed in the cart.

• Marketplace needs to simulate the cart to check the Seller's price and inventory.

OBS: when the client proceed to checkout, another cart simulation must be made.

• Order is closed in Marketplace.
• Marketplace adds the order to the Seller's endpoint.
• Order payment is completed in the Marketplace.
• Marketplace calls the Seller's endpoint to authorize the order's dispatch.

• Seller calls the Marketplace Services Endpoint to perform three possible final actions:
• Give invoice details.
• Give the carrier tracking code.
• Submit cancellation request.

1. Cart simulation.
2. Place order with the Seller.
3. Authorize order dispatch with the Seller.
4. Report Invoice.
5. Report carrier tracking.
6. Submit cancellation request.

For more information, see the documentation for developers External Marketplace.