When integrating a VTEX store with an external service such as an ERP, you need to set up a method for that service to retrieve order details and updates. For this scenario, VTEX provides the Order Feed and Order Hook tools, and this tutorial is meant to help you configure them in general terms.
Order Flow
First of all, it’s important to understand the lifecycle of an order within VTEX’s OMS. Every order, from creation through completion or cancellation, has a defined status that changes as different steps are taken — for example, order creation (order-created), the start of the cancellation window (window-to-cancel), or the start of the fulfillment process (ready-for-handling). Various VTEX modules use this status to trigger order-related processes (such as payment or logistics), and the Order Feed and Order Hook are a way to view and make use of these statuses directly. A full list of statuses and a summary of the order flow can be found in our documentation here.
What is the Order Feed?
The Order Feed is, in short, a history of all the statuses/changes an order has gone through since it was created. As an order is updated, the Feed saves that information for the external service to use until it is cleared by sending a commit request.
What is the Order Hook?
Whereas the Order Feed is a complete status history, the Order Hook is a notification sent directly to a given endpoint when a condition is met. For example, an Order Hook can be configured so that whenever an order’s payment is approved (status payment-approved), the ERP is notified to proceed with the order.
Which one should I use?
The choice of which method to use in your integration should be made together with the service being integrated, taking into account its own architecture and operational capacity. In general, VTEX recommends using the Order Hook when the top priority is status update speed. This is because the Order Hook, by nature of being a notification, is reactive and can send multiple requests in a short period of time, keeping up with order changes. However, many services may not have the infrastructure to scale their processing during notification spikes (e.g. Black Friday sales), or they may prioritize a broader view of each order’s status history. In that case, the Order Feed would be the preferable option.
How do I configure the Order Feed?
The Order Feed is configured via API using the POST Create or update feed configuration request. The request body must include a filter field and a queue field, and can be configured in two ways: using the FromWorkflow type or the FromOrders type.
FromWorkflow
The example below shows a FromWorkflow Feed configuration:
{
"filter": {
"type": "FromWorkflow",
"status": [
"order-completed",
"ready-for-handling",
"start-handling",
"handling",
"waiting-ffmt-authorization",
"cancel"
]
},
"queue": {
"visibilityTimeoutInSeconds": 250,
"MessageRetentionPeriodInSeconds": 345600
}
}
A FromWorkflow feed uses the Order Flow described above, allowing orders to be filtered based on the statuses they have passed through.
FromOrders
On the other hand, the example below shows a FromOrders Feed configuration:
{
"filter": {
"type": "FromOrders",
"expression": "status = \"payment-pending\""
},
"queue": {
"visibilityTimeoutInSeconds": 250,
"MessageRetentionPeriodInSeconds": 345600
}
}
A FromOrders feed takes into account not the order status, but the order’s entire JSON. Whenever any piece of order data is updated, the Feed is updated according to the configuration in the expression field.
In both cases, as shown in the examples, you need to define the Feed’s timing settings within the queue field. The visibilityTimeoutInSeconds field is used to ensure that multiple commits don’t occur for a given Feed. When the external service retrieves Feed updates, the items won’t be visible to other requests for the configured duration. The MessageRetentionPeriodInSeconds field, on the other hand, defines the total amount of time an item can remain in the feed without being committed. It’s important that items in the Feed are either committed or cleared, so the Feed doesn’t get cluttered with stale information.
Once the Order Feed is configured, it’s up to the external service to periodically fetch information from it and commit items after processing them. This can be done using the following APIs:
Retrieve feed items
Commit feed items
How do I configure the Order Hook?
Similarly, the Order Hook needs to be configured via API using the Create or update hook configuration request. The request body uses the same type of information for the filter field described above, but instead of the queue field, you need to use the hook field:
{
"filter": {
"type": "FromOrders",
"expression": "value > 100",
"disableSingleFire": false
},
"hook": {
"url": "https://endpoint.example/path",
"headers": {
"key": "value"
}
}
Within it, the url field defines the endpoint that will be notified and the headers field defines any header information required by that endpoint. Since the Hook is a notification, the external service doesn’t need to call any additional APIs after it has been configured.
In our complete documentation on Feed and Hook, found here, you can find more details on the possible values for each of the fields described above, examples of possible configurations, and more information on which scenarios the Feed and Hook are recommended for.
Eduardo Luciano
Field Software Engineer | VTEX