A marketplace is the environment where the product is sold, or the storefront. The seller owns the product and is responsible for fulfillment. VTEX promotes digital collaboration by allowing multiple combinations of architecture between these two entities. One of these combinations is called Multilevel Omnichannel Inventory.

Multilevel Omnichannel Inventory is the VTEX setting that allows franchises or white label sellers' inventory to be sold in marketplaces to which the main account is connected.

For VTEX sellers, this means being able to sell products from its franchises or white label sellers in a marketplace, without the need to set up the integration with the desired marketplace for all franchise stores, and white label sellers.

For marketplaces, this means selling products from its direct sellers and also physical stores and white label sellers associated with those sellers in a scalable way.

This article covers the account architecture details, chain order flows and necessary settings for VTEX marketplaces to implement this feature via API.

To know how to implement this feature via VTEX Admin, along with benefits and restrictions around the use of Multilevel Omnichannel Inventory, check out our Multilevel Omnichannel Inventory Help article.

When a store sells its products in a marketplace, we have a one-level relationship between seller and marketplace. However, VTEX's architecture allows stores to act as both sellers and marketplaces, expanding the number of possible combinations.

Stores that have white label sellers and franchises are marketplaces to those accounts. But they can also be connected to external marketplaces, becoming sellers themselves. In this case, we have a three level architecture, as illustrated in the image below.

• Marketplace (level 1): storefront where the product is sold and order is placed.
• Direct seller (level 2): main account, integrated to the marketplace level 1. Serves as a marketplace for white label sellers, franchise accounts and physical stores connected to it.
• Franchise accounts/physical stores (level 3): owns the product, and is responsible for fulfillment. Connected as white label sellers to the main account.

With the Multilevel Omnichannel Inventory setting, all franchise accounts and white label sellers (level 3) are already fully integrated to a store's main account (level 2). This means that when the main account sets up an integration with an external marketplace (level 1), the franchise accounts can be integrated as well, no longer being necessary to manage each franchise individually in order to set up its integration with the marketplace.

This feature is valid for VTEX marketplaces, native connectors and certified partners.

The Multilevel Omnichannel Inventory also affects an order's flow. The order flow describes the status, possibilities, and actions throughout the life cycle of an order. With the flow, retailers can also track the mapped order status on the platform. The table below summarizes all types of order flows that VTEX supports.

Order source and destination	Order type and workflow
VTEX store is the source of an order →	Marketplaceorder with Checkout Workflow.
VTEX store is intermediate in the order flow →	Chainorder with Chain Workflow.
VTEX store is the destination of an order →	Sellerorder with Fulfillment Workflow.
VTEX store is both the source and the destination →	Completeorder flow with Fulfillment workflow.

The Multilevel Omnichannel Inventory setting allows the entire inventory from a physical store network to be integrated into marketplaces, creating chain orders.

Let's break down how chain orders are applied in Multilevel Omnichannel Inventory architecture:

• Order originates in the marketplace (level 1).
• Order goes through an intermediate agent, in this case, the direct sellers (level 2).
• Order reaches its destination, to be fulfilled by the white label sellers (level 3).

Therefore, chain orders in direct seller have characteristics that come from both marketplaces, because they take the role of a seller's marketplace, and sellers, since they are also sellers of a marketplace.

Check out the order flow for chain orders in the image below:

The order flow seen by the level 2 store in a Multilevel Omnichannel Inventory is similar to the marketplace order flow, except for receiving the payment for orders. In the Payment pending stage, instead of the chain receiving payment directly from the gateway, the marketplace informs the chain it has received the payment confirmation.

VTEX stores cannot use the change order feature for chain orders made in VTEX marketplaces. However, it is possible to Change chain orders in external marketplaces.

The setup for Multilevel Omnichannel Inventory must be made by the marketplace through their VTEX Admin or REST API. This setup can be made in sellers that are already integrated, or sellers being added for the first time.

To configure Multilevel Omnichannel Inventory via REST API:

1. The marketplace must call the endpoint Configure Seller Account.

2. Fill the fulfillmentEndpoint field with the seller's checkout endpoint, following the example below:

3. Substitute the placeholders for the following values:

• sellerAccount: account name of the seller in VTEX.

• affiliateId: the 3-digit afiliate identification code created by the seller. The seller must inform this ID to the marketplace so that the marketplace can complete the configuration process.

• salesChannel: Sales channel (or trade policy associated to the seller account created. The seller must inform this ID to the marketplace so that the marketplace can complete the configuration process.

---

Checkout the API Integration article to learn how to external marketplace integrations, and headless architectures can make Multilevel omnichannel inventory available for their sellers.