[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides orders feed in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/master-data)

---

Payments

---

Orders

[Feed v3](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed)

[Order modifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/order-modifications)

[Change seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/change-seller)

[Cancel order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/order-canceling-improvements)

[Actions in orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/actions-orders)

Subscriptions

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/vtex-platform-overview)

---

[API usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/api-usage)

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/catalog-integration)

---

[Checkout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/checkout-api-overview)

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/master-data)

---

Payments

---

Orders

[Feed v3](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed)

[Order modifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/order-modifications)

[Change seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/change-seller)

[Cancel order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/order-canceling-improvements)

[Actions in orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/actions-orders)

Subscriptions

---

Logistics

---

B2B Suite

---

VTEX Sales App

---

UI Customization

---

Message Center

---

Pricing

---

Promotions

---

Infrastructure

---

Search

---

Storefront Permissions

---

[VTEX Activity Flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides)

Orders

[Feed v3](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed)

Feed v3

The [order feed](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview%23feed-v3) is a list of order updates. This means that whenever an order is updated, the event is included as a new entry in the feed. Updates can include status changes, items added or removed by the store, order delivered, and others.

In this sense, the feed is not a list of orders, but rather a list of events. For example, if the status of an order is changed to `Approve payment` and then to `Authorize shipping`, the feed will receive two events: one for each update, both related to the same order. You can configure the feed to filter the updates that will actually generate feed events, instead of having all updates in all orders generating events in the feed queue.

This guide explains how Feed and Hook work and how to configure them to build order integrations. Also, in the latter part of the article, we explain the differences between each and when to choose one over the other based on the specific needs of your operation.

> Feed and Hook are independent configurations to build order integrations.

## Best practices for integrations

When designing an orders integration, consider the practices below to increase performance and avoid throttling errors:

* Optimize your code to get only the required data.
* Use caching for often-used data.
* Consider including code that catches errors. By ignoring these errors and persisting in making requests, your app will not be able to recover gracefully.
* After getting a 429 status code error, you should stop making additional API requests and wait before retrying. We recommend a 1-minute backoff time.
* Configure your integration to communicate asynchronously with VTEX APIs in order to keep requests in a queue and do other processing tasks while waiting for the next queued job to run.

> If your integration is getting 429 status code errors, we recommend you to regulate the rate of your requests for smoother distribution. When the account exceeds the request limit, VTEX Admin might also become unavailable.

## Order integration: Feed vs. List orders

Some stores use the List orders API request to check order status changes. However, this method only returns orders that have already been indexed, which may lead to some problems:

* If a problem in the system prevents indexing, you will not be able to consume the order list, and order updates may not be visible.
* Because the `list` method depends on indexing, it's slower and performs less than the feed.

On the other hand, the feed has been specifically developed to track order updates. It runs before indexing and doesn't depend on it, making it the most reliable and fastest method to track order updates.

> If you have an integration based on the List orders API request, you should migrate it to the feed. However, keep in mind that this means changing the integration flow. Read the [order integration guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/erp-integration-set-up-order-integration) to learn how to implement this change.

## Access

Configuring and using Feed v3 and Hook is only allowed when authorization is granted in the Order Management module.

The feed's API key must have a [role](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc%23) with one of the appropriate resources: `Feed v3 and Hook Admin` or `Feed v3 and Hook view only`, depending on the intended use.

> Each [appKey](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/api-keys--4bFEmcHXgpNksoePchZyy6) can configure or access only one feed. This means that different users sharing an appKey access the same feed. In this case, if a user commits an item to the queue, the item is removed from the feed and won't be available for any users sharing the same appKey. Therefore, we recommend configuring one feed per appKey per user, ensuring that each user has access to their own feed.

## Configuration

The feed is set up through a POST request to the [Create or update Feed configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/orders/feed/config) endpoint.

The body of this request has two objects, the `filter` and the `queue`.

### `filter`

When you configure the filter, you define which order updates should be displayed in the feed. Two types of filters can be used in the feed: `FromWorkflow` and `FromOrders`. You can see an example and description of each filter below.

#### `FromWorkflow`

When you use the `FromWorkflow` configuration, you can only filter order updates by status. You can pass an array of statuses in the field `status`, and whenever an order status is changed to one of those statuses, an update will appear in the feed.

You can see the list of possible order statuses in the article [Order flow in orders management](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/fluxo-de-pedido/%23understanding-the-status).

`1

"filter": {

2

 "type": "FromWorkflow",

3

 "status": [

4

 "order-completed",

5

 "ready-for-handling",

6

 "start-handling",

7

 "handling",

8

 "waiting-ffmt-authorization",

9

 "cancel"

10

 ]

11

 }

`

> The `FromWorkflow` filter may be limited for some of the integration needs of your store. If you want more filter options, consider using the `FromOrders` filter.

#### `FromOrders`

`FromOrders` allows you to filter updates in your feed by any property in the order JSON document, not only status changes. This is done with a JSONata expression passed in the `expression` field.

`1

"filter": {

2

 "type": "FromOrders",

3

 "expression": "status = \"payment-pending\"",

4

 "disableSingleFire": false

5

 }

`

> The two filter types are mutually exclusive. If you pass `FromWorkflow` in the `type` field, you should not include the `expression` field nor `disableSingleFire` in the body. The reverse is also true. If you pass `FromOrders` `type`, you should not include the `status` field. If you combine them, you will get a `409 conflict` status response.

> If the `filter` is not configured, the `FromWorkflow` type is used, and all status changes will appear in the feed.

##### `expression`

This field receives a string with a JSONata query expression that defines what conditions must be met for an order to be included in the feed.

JSONata is a query and transformation language for JSON data. You can learn more about it in the [JSONata documentation](https://read.calvincode.net/reader?url=https://docs.jsonata.org/overview.html).

This filter offers many possibilities that can't be achieved with the `FromWorkflow` configuration. For example, you can filter orders that have been delivered or had items added or removed by the store. You can also combine two or more selection criteria. See the examples below:

* Delivered orders

`1

finished = true

`

* Orders with added items

`1

$count(changesAttachment.changesData.itemsAdded) > 0

`

* Orders with removed items

`1

$count(changesAttachment.changesData.itemsRemoved) > 0

`

You can also filter multiple properties at the same time. For example, the following is an expression that filters orders that contain at least one refrigerator that costs at least $1000.00:

`1

$count(items[name ~> /.*refrigerator.*/i and price>=1000]) > 0

`

Here are some additional expression examples:

* Order in specific status and trade policy (sales channel)

`1

(status = "ready-for-handling" and salesChannel="2")

`

* Orders from a seller that don't have a specific [trade policy](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV) (sales channel)

`1

(salesChannel.Id != "3" and sellers.id ="sellerId")

`

* Order with refund/item return

`1

$count(packageAttachment.packages.restitutions.Refund.value) > 0

`

* Order invoiced with a specific shipping policy

`1

status = "invoiced" and (packageAttachment.packages[$[$contains($string(courier), "Carrier Name")]])

`

> Keep in mind that the `expression` field receives only strings and all JSONata expressions have to be escaped. For example, the expression `status = “canceled”` has to be passed as `”status = \\”canceled\\””` to be read correctly by the API.

The following is an example of a complete `filter` object with a more complex and escaped JSONata expression.

`1

"filter": {

2

 "type": "FromOrders",

3

 "expression": "(status = \"handling\" and salesChannel = \"2\" and $count(packageAttachment.packages.restitutions.Refund.value) > 0)",

4

 “disableSingleFire”: false

5

},

`

##### Expression tests

You should validate the events of the configured expression before implementing the filter in your integration. There are three useful tests:

* [The API endpoint for JSONata Testing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/orders/expressions/jsonata).
* [JSONata Exerciser](https://read.calvincode.net/reader?url=https://try.jsonata.org/) which tests the expression against a real JSON file. To run this test, copy the order to JSONata Exerciser and simulate different expressions and requests. Use an order extracted from the [Get order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api-pii-version%23get-/api/orders/pvt/document/-orderId-) endpoint from the [Orders API - PII data architecture](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api-pii-version%23overview).
> Be aware that the [Get order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api-pii-version%23get-/api/orders/pvt/document/-orderId-) endpoint from **Orders API - PII data architecture** differs from the [Get order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/oms/pvt/orders/-orderId-) endpoint from **Orders API**.
* Configure a test feed or hook with a test [appKey](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/getting-started-authentication) and check whether the events behave as expected.

##### `disableSingleFire`

This field limits how often a specific order shows in the feed after it meets the filter conditions. If this field is `false`, orders will appear in the feed only once.

> The `FromOrders` filter receives order updates whenever any change is made to the order JSON document, provided the order meets the criteria set in the `expression` field. Because of this, if the `disableSingleFire` field is set to `true`, orders may appear more than once in a feed — even hundreds of times in some cases. To prevent that from happening, keep `disableSingleFire` set to `false`.

### `queue`

The properties of this object define the behavior of feed items once they are included in the feed or are retrieved. This is an example of the `queue` object:

`1

"queue": {

2

 "visibilityTimeoutInSeconds": 240,

3

 "messageRetentionPeriodInSeconds": 345600

4

 }

`

* `visibilityTimeoutInSeconds` \- This is the maximum time after retrieving an item from the feed when it can be [committed](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/orders/feed). When a user retrieves the events from the feed queue using the [Retrieve Feed items](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/orders/feed) API request, the returned items are omitted from the feed for the time set in this field. Then, the user may take any necessary actions and [commit](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/orders/feed) the items to the feed. If events are not committed, they are returned to the feed after this time expires.
* `MessageRetentionPeriodInSeconds` \- Items will be excluded from the feed — even if they aren't [committed](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/orders/feed) — when they stay in the feed longer than the retention period defined in this field.

> The minimum value for the `messageRetentionPeriodInSeconds` field is `345600` and the maximum is `1209600`.

### Other fields

There are also a couple of other fields that give us some information about the state of the field:

* `quantity`: Current number of messages in the feed, including messages that may not be visible due to time out after retrieval.
* `approximateAgeOfOldestMessageInSeconds`: Approximate age of the oldest message in the feed (in seconds).

### Examples

Here are two complete example bodies for the [Feed configuration response](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/orders/feed/config), using each `filter` type:

`1

{

2

 "filter": {

3

 "type": "FromWorkflow",

4

 "status": [

5

 “order-completed”,

6

 "ready-for-handling",

7

 “start-handling”,

8

 “handling”,

9

 “waiting-ffmt-authorization”,

10

 “cancel”

11

 ]

12

 },

13

 "queue": {

14

 "visibilityTimeoutInSeconds": 240,

15

 "messageRetentionPeriodInSeconds": 345600

16

 },

17

 "quantity": 1261,

18

 "aproximateAgeOfOldestMessageInSeconds": 1113.349305555555

19

}

`

`1

{

2

 "filter": {

3

 "type": "FromOrders",

4

 "expression": "status = \"payment-pending\"",

5

 "disableSingleFire": false

6

 },

7

 "queue": {

8

 "visibilityTimeoutInSeconds": 240,

9

 "messageRetentionPeriodInSeconds": 345600

10

 },

11

 "quantity": 1261,

12

 "aproximateAgeOfOldestMessageInSeconds": 1113.349305555555

13

}

`

> When a new feed is configured, its queue contains any orders that are changed right after the setup is complete. If the feed is reconfigured, events from the former queue will remain in the feed until they are [committed](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/orders/feed) or the retention period expires.

> If the feed doesn't receive any new events in its queue during the time set in `messageRetentionPeriodInSeconds`, your configuration will be removed, and you will have to reconfigure it with the [Feed configuration API call](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/orders/feed/config) to continue using the feed. Therefore, it's important to be mindful of the filter configuration you are using. You can check it any time using the [Get feed configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/orders/feed/config) endpoint.

## Feed readout

Every system that depends on order updates should consume the feed to be able to take the necessary actions based on that information. The most common behavior is a store system or an integration reading every event in the feed and, based on its status, making a decision for each one.

> When filtering statuses, be aware that all possible order statuses must be dealt with during integration to avoid errors. Particular attention should be paid to `Status Null`, which may be unidentified and end up being mapped as another status, which can potentially lead to errors.

### Example

The order feed can be useful in many ways. For instance, say you want to develop an integration between your ERP and VTEX. This integration could have the following behavior:

1. It retrieves ten events from the feed.
2. For each one of the ten events, it evaluates the status the order was changed to.
3. If the order changed to the status `Ready for handling`, the integration gets the complete order data, records it in the ERP, and updates the status on VTEX to `Handling shipping` (which indicates the start of handling).
4. Then, it commits the events to the Feed (removing them from the queue).
5. After reading and removing these ten events from the list, the integration moves to the following ten events in the feed and repeats the process.

![{"base64":"  ","img":{"width":250,"height":472,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":37671,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/orders-feed-0.png"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/orders-feed-0.png)

Check the [back-office order integration guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/erp-integration-set-up-order-integration) to learn more about how you can integrate the VTEX order feed with an ERP.

## Hook

Hook is a counterpart to Feed. It allows integrations to consume order update data differently. Instead of receiving events to form a queue that can be retrieved, a hook automatically sends the items to a URL provided by the user in the hook configuration.

> Since Hook is a counterpart, [access](#access) follows the same principles described for Feed above. This means each appKey can configure or access only one hook. Different users that sharing the same appKey access the same hook. We recommend configuring one hook per appKey per user, ensuring that each user has access to their own hook.

### Hook configuration

Similar to a feed, a hook can be configured through a POST call to the [Create or update hook configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/orders/hook/config) endpoint of the Orders API. Here are a couple of body examples for the request, each using a different filter type:

`FromWorkflow`

`1

{

2

 "filter": {

3

 "type": "FromWorkflow",

4

 "status": [

5

 "payment-pending"

6

 ]

7

 },

8

 "hook": {

9

 "url": "https://endpoint.example/path",

10

 "headers": {

11

 "key": "value"

12

 }

13

 }

14

}

`

`FromOrders`

`1

{

2

 "filter": {

3

 "type": "FromOrders",

4

 "expression": "status = \"payment-pending\"",

5

 "disableSingleFire": true

6

 },

7

 "hook": {

8

 "url": "https://endpoint.example/path",

9

 "headers": {

10

 "key": "value"

11

 }

12

 }

13

}

`

As you can see, the `filter` object is configured the same way as the `filter` in the feed configuration described above. The other object in the body is the `hook` object, which contains information about how the data should be sent to the integration:

* `url` is the endpoint path that should receive the order update information.
* `headers` contains the credentials that should be used to access the given endpoint.
* `key` is the endpoint key that should be used to access the given endpoint.

When the hook is configured, VTEX sends a ping to the endpoint given in the configuration request body to ensure it is up and running. It is a `POST` request similar to this:

`1

{

2

 "hookConfig": "ping"

3

}

`

> The given endpoint should return status 200 for the above-mentioned request. Otherwise, the Hook API will return status `400 Bad Request`, and you won't be able to save the configuration.

> We recommend configuring the hook in the main account. This ensures more visibility to commit all events correctly and that the configured endpoint is more frequently notified, preventing the hook from being excluded due to inactivity.

### Hook notifications

If configured, the Hook notifies the integration endpoint whenever an order update is made and meets the conditions specified in the `filter`.

If a new event is not correctly notified to the endpoint, the interval for future retries is recalculated based on an internal geometric progression algorithm.

> If the hook has no notifications for three days, your configuration will be removed, and you will have to reconfigure it with the [Hook configuration API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/orders/hook/config) call to continue using it. Therefore, it's important to be mindful of your filter configuration. You can check it any time using the [Get hook configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/orders/hook/config) endpoint.

> When notified, the configured endpoint must always respond with HTTP status 200 within 5000 ms. Below is an example of a hook notification request body made to the integration endpoint.

`1

{

2

 "Domain": "Marketplace",

3

 "OrderId": "v40484048naf-01",

4

 "State": "payment-approved",

5

 "LastChange": "2019-07-29T23:17:30.0617185Z",

6

 "Origin": {

7

 "Account": "accountABC",

8

 "Key": "vtexappkey-keyEDF"

9

 }

10

}

`

> When using a hook, it's important to be aware that it's a reactive feature. This means your middleware or ERP system must be ready to deal with whatever volume of data the hook sends. Large peaks in sales – due to Black Friday, for example – tend to increase hook notifications. If the implementation is not prepared for this peak, it may cause problems in the integration, compromising the store’s ability to handle orders and receive further notifications. Learn more about how to deal with this issue in the next section. Getting order updates from a feed requires the integration to make periodical API calls, returning whatever number of available updates each time, with no guarantee of ordination due to the infrastructure and technology used. A hook, on the other hand, notifies the integration whenever a new update is available. This means a feed is active, whereas a hook is reactive.

Because of this, a hook can be more efficient and provide a lower response time for each order update. But as a reactive feature, the integration must have scalability to handle great variations in data volume, such as can be caused by a Black Friday sales peak, for example.

Some ERPs, for instance, do not have this scaling capacity. If you integrate a hook with an ERP, a possible workaround is to build middleware that is able to handle large variations in the data volume received from the hook and have the integration send the data to the ERP at a lower speed based on the capacity of the ERP.

Another option is using a hook as the primary source of data for the integration and a feed as a backup source that may be used when the hook integration has trouble scaling.

We recommend a hook for larger and more complex operations, which tend to have greater middleware scalability capacity and can benefit more from the feature’s efficiency.

On the other hand, a feed requires active [retrieving](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23get-/api/orders/feed) and [committing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/orders/feed) items to the queue. This means the integration has control over how many order updates it receives, and it knows how much data it needs to be able to handle at any given time. For this reason, it is less likely for the integration to crash or miss updates from the queue.

To learn more, read the [order integration with ERP](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/erp-integration-set-up-order-integration) guide and the API reference for [Feed v3](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/reference/feed-v3) and [Hook](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-overview%23creating-an-order-integration).

Contributors

3

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F170467615%3Fv%3D4%26w=64%26q=75)](https://github.com/mariananantua)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77300325%3Fv%3D4%26w=64%26q=75)](https://github.com/Isabella-Veloso)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Orders/orders-feed.md)

[Metadata information in payment transactions« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed//docs/guides/metadata-information-in-payment-transactions)[Order modificationsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed//docs/guides/order-modifications)

Contributors

3

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F170467615%3Fv%3D4%26w=64%26q=75)](https://github.com/mariananantua)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77292838%3Fv%3D4%26w=64%26q=75)](https://github.com/julia-rabello)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F77300325%3Fv%3D4%26w=64%26q=75)](https://github.com/Isabella-Veloso)

ON THIS PAGE

[Best practices for integrations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23best-practices-for-integrations)

[Order integration: Feed vs. List orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23order-integration-feed-vs-list-orders)

[Access](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23access)

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23configuration)

[filter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23filter)[queue](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23queue)[Other fields](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23other-fields)[Examples](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23examples)

[Feed readout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23feed-readout)

[Example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23example)

[Hook](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23hook)

[Hook configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23hook-configuration)[Hook notifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23hook-notifications)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/Orders/orders-feed.md)

Copy page

On this page

ON THIS PAGE

[Best practices for integrations](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23best-practices-for-integrations)

[Order integration: Feed vs. List orders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23order-integration-feed-vs-list-orders)

[Access](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23access)

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23configuration)

[filter](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23filter)[queue](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23queue)[Other fields](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23other-fields)[Examples](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23examples)

[Feed readout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23feed-readout)

[Example](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23example)

[Hook](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23hook)

[Hook configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23hook-configuration)[Hook notifications](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/orders-feed/docs/guides/orders-feed%23hook-notifications)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] How do I use the VTEX product summary 2.91.0 ProductSummarySKUSelector app? Provide documentation and configuration details.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/vtex-io-deprecated-apps)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/guides/vtex-io-deprecated-apps)

---

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/vtex-io-apps)

Product Summary SKU Selector

[vtex.product-summary](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary)

Version: 2.91.0

Latest version: 2.91.0

The `product-summary-sku-selector` is a VTEX block that's tasked with rendering the [SKU Selector](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-developer-docs/docs/vtex-store-components-skuselector) component in a Product Summary component, such as the Shelf or the Search Results Page.

![{"base64":"  ","img":{"width":2224,"height":1302,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":767184,"url":"https://user-images.githubusercontent.com/52087100/68625690-87f9a580-04b8-11ea-835d-009ac768805f.gif"}}](https://read.calvincode.net/reader?url=https://user-images.githubusercontent.com/52087100/68625690-87f9a580-04b8-11ea-835d-009ac768805f.gif)

## Configuration

1. Follow the [Product Summary](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-developer-docs/docs/vtex-product-summary) app's configuration instruction.
2. Add the `product-summary-sku-selector` to the Product Summary's desired block. In the following example, we'll use a Shelf:

`1

"product-summary.shelf": {

2

 "children": [

3

 "product-summary-add-to-list-button",

4

 "stack-layout#prodsum",

5

 "product-summary-name",

6

 "product-rating-inline",

7

 "product-summary-space",

8

 "product-summary-sku-selector",

9

 "product-summary-price",

10

 "product-identifier.summary",

11

 "product-summary-buy-button"

12

 ]

13

 },

`

1. Below, declare the `product-summary-sku-selector` block. The props that it uses are the same that are available for the [SKU Selector](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-developer-docs/docs/vtex-store-components-skuselector). For example:

`1

 "product-summary-sku-selector": {

2

 "props":{

3

 "showVariationsLabels": ["false"]

4

 }

5

},

`

> The Product Summary SKU block can only be modified through the source code. It's not possible yet to edit it via the Site Editor.

## Customization

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on [Using CSS Handles for store customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-developer-docs/docs/vtex-io-documentation-using-css-handles-for-store-customization).

| CSS Handles          |
| -------------------- |
| SKUSelectorContainer |

See also

[Vtex.product SummaryVTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/apps/vtex.product-summary)[VTEX App StoreVTEX IO Apps](https://read.calvincode.net/reader?url=https://apps.vtex.com/)

ON THIS PAGE

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector%23configuration)

[Customization](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector/docs/apps/vtex.product-summary@2.91.0/ProductSummarySKUSelector%23customization)

Was this helpful?

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)


[System] You are a VTEX documentation expert. You provide accurate, detailed information about VTEX platform, APIs, apps, and Store Framework development.

[User] Provide a guide on guides vtex io documentation pixel builder in VTEX.

[Assistant]
Documentation

[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)

[GuidesLearn how to use our APIs and extend the VTEX platform.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/api-reference)

[App DevelopmentLearn how to build cloud-based apps and integrations.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/storefront-development)

[VTEX IO AppsFind pre-built solutions to grow your business.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/troubleshooting)

[Release NotesStay up to date with our latest releases and bug fixes.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-getting-started)

---

Project structure

[Manifest](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-manifest)

[Billing Options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-billing-options)

[Builders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-builders)

[Admin Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-admin-builder)

[Assets Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-assets-builder)

[Docs Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-docs-builder)

[GraphQL Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-graphql-builder)

[Messages Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-messages-builder)

[Node Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-node-builder)

[PaymentProvider Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-paymentprovider-builder)

[Pixel Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-pixel-builder)

[React Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-react-builder)

[Store Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-store-builder)

[Styles Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-styles-builder)

[Dependencies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-dependencies)

[Peer Dependencies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-peerdependencies)

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/app-development-guides)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/updates/release-notes)

App Development

[What is VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-what-is-vtex-io)

---

[What is a VTEX App](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-what-is-a-vtex-app)

---

[Governance and shared security in VTEX IO apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/governance-and-shared-security-in-vtex-io-apps)

---

[Code samples and templates](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/code-samples)

---

[Getting Started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-getting-started)

---

Project structure

[Manifest](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-manifest)

[Billing Options](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-billing-options)

[Builders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-builders)

[Admin Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-admin-builder)

[Assets Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-assets-builder)

[Docs Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-docs-builder)

[GraphQL Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-graphql-builder)

[Messages Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-messages-builder)

[Node Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-node-builder)

[PaymentProvider Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-paymentprovider-builder)

[Pixel Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-pixel-builder)

[React Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-react-builder)

[Store Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-store-builder)

[Styles Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-styles-builder)

[Dependencies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-dependencies)

[Peer Dependencies](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-peerdependencies)

---

[VTEX IO CLI](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-vtex-io-cli-installation-and-command-reference)

---

[Workspace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-workspace)

---

Managing apps

---

Development guides

---

[Node apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/app-development-guides)

---

[GraphQL in VTEX IO](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/graphql-in-vtex-io)

---

[Policies and permissions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-policies)

---

[A/B tests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/ab-tests)

---

[Deployment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-making-your-new-app-version-publicly-available)

---

[VTEX App Store](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-app-store)

---

[Edition Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/managing-edition-apps)

---

[Frequently asked questions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-frequently-asked-questions)

---

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/app-development)

Project structure

[Builders](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-builders)

[Pixel Builder](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-pixel-builder)

Pixel builder

Learn how to use the VTEX IO Pixel builder.

The `pixel` builder allows the implementation of JavaScript scripts in HTML files. The scripts run in the head or body of every store page and can collect user data, respond to events, and connect with third-party services.

For details about creating Pixel apps, see the [Pixel apps tutorial](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-1-developnativeintegrationswithpixelapps). You can find examples of available apps that use this builder in the [Pixel Apps section](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/pixel-apps).

## Folder structure

The `pixel` builder uses a folder named `pixel` located in the app’s root folder.

`1

pixel

2

 ┣ 📄body.html

3

 ┗ 📄head.html

`

* `body.html`: HTML file with the script that will run in the body of the store pages. Scripts running in the body can perform better, but some events might be missed since the execution takes place while HTML elements are rendered.
* `head.html`: HTML file with the script that will run in the head of the store pages. Running scripts in the head can have a higher impact on performance but ensures all events are detected since the execution takes place before HTML elements are rendered.

## Usage

1. **Start with a template:** Download the [pixel-app-template](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/pixel-app-template/).
2. **Add the app settings to the manifest:** Open the `manifest.json` file in the app’s root folder and add the necessary settings to work with your script in the `settingsSchema` object. For example, you can add a field to insert a Google Tag Manager ID. For more details, see [Creating an interface for your app settings](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-creating-an-interface-for-your-app-settings).
3. **Implement the script:** Insert the script code in the `head.html` file or `body.html` file, depending on the desired implementation. The script will run on every store page. The choice between head or body execution is a trade-off of page performance against ensuring event detection and user data collection. Below is a script example.
`1
<script>
2
 (function() {
3
 var appId = "{{settings.gtmId}}";
4

5
 // Add script here
6
 })()
7
</script>
`
4. **Add scripts in specific pages or components (optional):** Besides running scripts with the `pixel` builder, you can add scripts in specific pages and components using React. You can see an example in the [Pixel apps tutorial](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-6-listeningtostoreevents). For the definition of the available events, see the [pixel-app-template](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/pixel-app-template/blob/master/react/typings/events.d.ts) repository.
5. **Testing:** [Link the app](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-linking-an-app) to a development workspace for testing, then access the store in the development workspace to see the script in action. The URL to access the store in the development workspace uses the format `{workspace}--{accountName}.myvtex.com`, where `{workspace}` is your workspace and `{accountName}` is your account name. You may need to perform the programmed actions to trigger the events set in your script, such as adding a product to the shopping cart.

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7026595%3Fv%3D4%26w=64%26q=75)](https://github.com/henriquessb)

Was this helpful?

Yes

No

[Suggest Edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Reference/concepts/vtex-io-documentation-builders/vtex-io-documentation-pixel-builder.md)

[PaymentProvider Builder« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder//docs/guides/vtex-io-documentation-paymentprovider-builder)[React BuilderNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder//docs/guides/vtex-io-documentation-react-builder)

Contributors

2

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F60782333%3Fv%3D4%26w=64%26q=75)](https://github.com/carolinamenezes)

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7026595%3Fv%3D4%26w=64%26q=75)](https://github.com/henriquessb)

ON THIS PAGE

[Folder structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-pixel-builder%23folder-structure)

[Usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-pixel-builder%23usage)

Was this helpful?

 Send feedback

[Suggest edits (GitHub)](https://read.calvincode.net/reader?url=https://github.com/vtexdocs/dev-portal-content/edit/main/docs/guides/vtex-io/Reference/concepts/vtex-io-documentation-builders/vtex-io-documentation-pixel-builder.md)

Copy page

On this page

ON THIS PAGE

[Folder structure](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-pixel-builder%23folder-structure)

[Usage](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/vtex-io-documentation-pixel-builder/docs/guides/vtex-io-documentation-pixel-builder%23usage)

On this page

[Github](https://read.calvincode.net/reader?url=https://github.com/vtex-apps)[Help Center](https://read.calvincode.net/reader?url=https://help.vtex.com/)[Community](https://read.calvincode.net/reader?url=https://community.vtex.com/?%5Fga=2.198523433.743584735.1647618303-1974737580.1645714642)[Feedback](https://read.calvincode.net/reader?url=https://docs.google.com/forms/d/e/1FAIpQLSfmnotPvPjw-SjiE7lt2Nt3RQgNUe10ixXZmuO2v9enOJReoQ/viewform?entry.1972292648=developers.vtex.com%26entry.1799503232=)