Tutorials & Solutions
Orders management
Inventory and shipping
Rates & Benefits
Master Data
Message Center
Sales Policies
Account management
Credit Control
Projects & Integrations

How the Orders Management Feed v3 works

Breno Barreto
Breno Barreto
Last updated

The feed can be thought of as a list of status change events on store orders, meaning that whenever there is a status change in an order, this change will be included as a new record in the feed.

The feed is therefore not an orders list, but rather an events list. For example, if an order changes its status to Approve Payment and then to Authorize Shipping, two records will exist in the feed: one for each status change, both referring to the same order.

Before getting the data from the orders queue, you need to configure Feed v3. Otherwise, when trying to get the data, the API would give you a 404 status.


Feed v3 configuration and use are only permitted by granting authorization in the Orders Management module.

The feed user must have his OMS Feed v3 and Hook access profile enabled.

How to use

The AppKeys used to access the feed must be untransferable. The simultaneous use of the same AppKey by more than one user will make each undertaken feed action have a great impact on data visualization.

Let's imagine that an event is committe by a user sharing the same AppKey with another user. According to the feed system, the event committed by one will be deleted in both their feeds.

The shared use of the feed can lead to the loss of important data form your event queue. Therefore, we recommend the configuration of one feed per user, ensuring each user has access to an exclusive feed.

Events queue

When queried by the user, the returned events queue is omitted from the feed by the visibilityTimeoutInSeconds field's defined time. This field belongs to the Feed Configuration API that will be committed, meaning that events returned in the Get feed order status API become invisible, no longer appearing is any further feed query for the duration of the time set in the field. When not committed, events are returned to the feed after the set time expires.

The duration of an event that is not committed in the feed queue is defined by the MessageRetentionPeriodInSeconds field in the Feed Configuration API. After the retention time expires, the event will be excluded from the feed and all data pertaining to it lost.

When a new feed is configured, its queue is made up of whichever status suffers changes starting from the moment of the configuration. If the feed is reconfigured, events corresponding to the former queue will be made available as usual through the use of a query, as long as these were within the set retention time of the new feed configuration.

Notice: Should the feed not receive any new events in its queue for 3 days, your configuration will be removed and you will have to run the setup again in order to give continuity to your store's events management. It is therefore imperative to be mindful of the status filter configured in the Feed Configuration API, since it defines which events are registered.

Feed readout

Every system that depends on order status changes should consume the feed to know the status changes and undertake the necessary actions based on that information. The most common behavior is therefore that of a store system or an integration reading every event in the feed and, based on the status, making a decision for each one.


Let's say that your store may want to develop an integration between your ERP and VTEX. This integration could have the following behavior:

  1. It reads 10 events from the feed
  2. For each one of these 10 events, it evaluates to which status the order was changed
  3. If the change was to the Ready for Handling status, the integration gets the complete order data, records it in the ERP, updates the status in VTEX to Preparing Delivery (informing the start of the handling), and removes the event from the feed list
  4. After reading and removing these 10 events from the list, the integration reads the next 10 events and repeats the whole process


Why use the feed

The feed has been developed specifically to track order status changes. It is a system dedicated for this task, and only an extremely serious incident would prevent a new status from entering the feed.

Some stores use the Orders Management order-listing method (list) to check order status changes. We do not recommend using the listing method for systems that depend on order status changes. Use the feed instead.

Why not use the list?

We do not recommend using the list method to consume changes in status because this method occurs after the order indexation. That is, the orders list brought by the list method is, in fact, the list of indexed orders.

This causes two problems for your store when your goal is to be kept up-to-date with status changes:

  • If any system issue prevents indexation, you will not be able to consume the order list and will not see the status changes.

  • Because it depends on indexation, the list method is slower and has a weaker performance than the feed.

Because the feed happens before indexation, it does not depend on it, making it more reliable and faster than the list.

Feed setup

Read our article on how to configure Orders Management module Feed v3.

Still got questions?
Ask the community
Find solutions and share ideas in VTEX's community.
Talk to our experts
Get in touch if you have something specific to ask about the platform.
  • PT
  • ES
VTEX website