API Reference

Getting started

Help us improve our documentation! Tell us about your experience with this article by completing this form.

This overview article covers the VTEX Order Management System (OMS), including relevant links from our developer documentation. In the following sections, you will find information about setting up and managing your orders, creating order integrations with external partners, and configuring optional settings.

Importing orders from an ERP or Back office

If your store has an ERP integration or another integration for managing orders, you will need to create an integration with the VTEX platform. The links below provide an overview of the order integration flow between a back-office system and a VTEX store.

Understanding order flow types

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

Marketplace flow

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

{"base64":"  ","img":{"width":9483,"height":5166,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":767240,"url":""}}

Seller flow

The seller order flow is only visible to the store responsible for handling the order.

{"base64":"  ","img":{"width":6258,"height":2556,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":321573,"url":""}}

Complete flow

The complete order flow is only visible to the store responsible for the sale and delivery. In this case, the store acts both as seller and marketplace.

{"base64":"  ","img":{"width":7611,"height":2102,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":320548,"url":""}}

Chain flow

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

{"base64":"  ","img":{"width":5419,"height":2952,"type":"jpg","mime":"image/jpeg","wUnits":"px","hUnits":"px","length":338064,"url":""}}

Creating an order integration

In the following sections, you will learn how to build order integrations with Feed and Hook. For example, this can be useful for developing an integration between your store ERP and the VTEX platform.

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 an order status update will be included as a new item in the feed whenever there is an event in an order.


Hook works as a complement to Feed, because it allows an integration to consume order updates data by sending items to a URL provided by the user in the Hook configuration.

Managing orders

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

Placing an order

Placing an order involves the Order Management module and Checkout. There are different paths to create orders. For more information about placing orders, 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 only access information from orders created in the last two years, and that same period is valid for customers through My Account.

You can fetch information about orders in multiple ways and about specific topics. To learn more about retrieving order content, see the links below.






Changing an order status

Every order has a life cycle registered as an order flow, which describes the order status, options, and updates. For more information, see the links below.

Changing an order

Changing orders is a feature that allows your store to edit the items or prices of an order. For example, this allows you to handle eventual changes due to customer mistakes or product unavailability. To learn more, see the links below.

Changing seller

Another seller can be selected to fulfill a given order after the original seller canceled it. The period when this can be done is called the change seller window. You can use the endpoints below for this.

Sending payment notification

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

If your store receives payments outside the VTEX platform, such as cash or notes payable, it must call this endpoint to notify the OMS, so the order can follow its flow and be fulfilled.

The endpoint Send 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 its status, except when you want to send a return invoice.

In that case, the Order invoice notification endpoint must be called, and instead of having the field type value defined 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 with a tracking number, use the Update order's partial invoice endpoint.

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

Integrating with the Multilevel Omnichannel Inventory

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

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 store can act as both a seller and a marketplace in relation to another VTEX store or an external partner. If you are an external marketplace that wants to integrate with VTEX sellers, see the links below to learn how to develop a custom connector to integrate with the VTEX architecture and seller orders.

Adding optional configurations

There are additional configurations available for you to manage your store orders. This allows you to take advantage of other VTEX features, such as VTEX Sales App, VTEX DO, B2B, and Master Data.

VTEX Sales App



Master Data

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