📣Help us improve our documentation!

Tell us about your experience with this article by filling out

This overview article goes over VTEX’s Order Management System (OMS), including relevant links from our developer documentation about this topic. In the following sections you will find information about setting up and managing your orders, creating order integrations with external partners and making optional configurations.

Importing orders from an ERP or Back office

If your store has an ERP integration or another kind of integration for managing orders, it will be necessary to make an integration with VTEX’s platform. The links below provide a general view of the integration flow between a back office system and a VTEX store regarding orders.

Understanding order flow types

The order flow describes the status, possibilities, and actions throughout the life cycle of an order. In VTEX, there are four order flows types:

Marketplace flow

The order flow visible to the store responsible for the sale only.

Seller flow

The order flow visible to the store responsible for handling the order.

Complete flow

The order flow visible to the store responsible for the order's sale and delivery. In this case, the store acts both as a seller and marketplace.

Chain flow

The order flow visible to the store that acts as an intermediary between the marketplace and the seller. This flow is similar to the marketplace flow. However, the payment is made only in the marketplace, not in the store that acts as a chain. This flow occurs in Multilevel Omnichannel Inventory sales scenarios.

Creating an order integration

In the following sections, you will learn how to build order integrations with the Feed and Hook. This is useful when you want to develop an integration between your store’s ERP and the VTEX platform, for example.

We strongly recommend you to create an order integration using the Orders Feed v3, instead of using the List orders API request or external services. If you already use an integration based on the API request, you should migrate to using the Feed. Keep in mind that this means changing the integration flow. To learn how to implement this change, see the Set up order integration.

Feed v.3

The Orders Feed is a list of order updates, meaning that whenever there is an event in an order, like an order status update, it will be included as a new item in the Feed.


The Hook is a complement to the Feed, which allows an integration to consume order updates data by sending items to an URL provided by the user in the Hook configuration.

Managing orders

There are several actions a VTEX store can perform on orders. In the next sections, you will find the main actions related to a store’s order management routine.

Placing an order

The action of placing an order involves both the Orders Management module and the Checkout, and there are different paths to create orders. For more information about order placement, see the links below.

The orderForm is the main object processed by the Checkout and it stores a lot of contextual information about an order. The orderForm fields will be present in most of OMS's API calls.

Retrieving order’s details

You can fetch information related to orders in multiple ways and about specific topics. To know more about retrieving orders’ content, see the links below.






Changing an order status

Every order has a life cycle registered in the form of an order flow, which describes the order’s status, possibilities, and updates. For more information, see the following links.

Changing an order

Change order is a feature that allows your store to modify the items or prices of an order. This allows you to handle eventual changes motivated by customer mistakes or product unavailability, for example. To know more, see the links below.

Changing seller

It is possible to choose another seller to fulfill a given order after the original seller canceled it. The period during which this action can be performed is called window to change seller, and you can use the endpoints below for this scenario.

Sending payment notification

For your payment provider to notify the Order Management System that the payment of a given order is completed, use te endpoint Send a payment notification.

In case your store receives the payments outside VTEX’s platform, like payments in cash or with promissories, the store must call this endpoint to notify the OMS, so that the order can follow its flow and be fulfilled.

The endpoint Send a payment notification must be called only after the order payment has been approved. The store might not receive the payment if there is an issue with the settlement and the endpoint has already been called.

Invoicing an order

When you invoice an order, its status in the order flow changes to Invoiced, which means the order was successfully completed. After an order is invoiced, you can no longer modify it’s status, except when you wish to send a return invoice.

In that case, the endpoint Order invoice notification must be called, and instead of having the field `type` value determined as Output, it will be Input.

Tracking an order

Every order has a tracking number that allows you to keep track of its status in the order flow. To send a tracking event to an order that already has a tracking number, use the endpoint Update order's partial invoice.

If you wish to register a tracking number and URL to an order’s invoice, use the endpoint Update order's partial invoice.

Integrating with the 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.

In other words, the feature allows VTEX sellers 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 marketplaces, this means selling products from their direct sellers and also physical stores and white label sellers associated with those sellers in a scalable way. For more information, see the article Multilevel Omnichannel Inventory.

Integrating orders from an external marketplace

A VTEX’s store can act both as a seller and a marketplace to another VTEX store or an external partner. If you are an external marketplace that wishes to integrate with VTEX sellers, see the links below to learn how to develop a custom connector to connect with VTEX's architecture and sellers’ orders.

Adding optional configurations

There are optional settings available for you to manage your store’s orders. This allows you to take advantage of other VTEX capabilities, such as inStore, VTEX DO, B2B and Master Data.