[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 impressions 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/impressions/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/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/impressions/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/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/impressions/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/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/impressions/updates/release-notes)

Guides

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

---

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

---

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

---

Integration Guides

---

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

---

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

---

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

---

Payments

---

Orders

---

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/impressions/docs/guides/activity-flow)

---

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

[Getting started with VTEX Ads API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/getting-started-with-vtex-ads-api)

[Synchronizing the catalog with VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/synchronizing-the-catalog-with-vtex-ads)

[Retrieving ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/retrieving-ads)

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

[Understanding ads events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/understanding-ads-events)

[Ads events notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/ads-events-notification)

[Impressions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/impressions)

[Views](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/views)

[Clicks](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/clicks)

[Conversion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/conversion)

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

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

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

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

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

---

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

Guides

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

---

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

---

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

---

Integration Guides

---

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

---

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

---

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

---

Payments

---

Orders

---

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/impressions/docs/guides/activity-flow)

---

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

[Getting started with VTEX Ads API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/getting-started-with-vtex-ads-api)

[Synchronizing the catalog with VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/synchronizing-the-catalog-with-vtex-ads)

[Retrieving ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/retrieving-ads)

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

[Understanding ads events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/understanding-ads-events)

[Ads events notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/ads-events-notification)

[Impressions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/impressions)

[Views](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/views)

[Clicks](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/clicks)

[Conversion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/conversion)

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

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

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

[Getting started with VTEX Ads API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/getting-started-with-vtex-ads-api)

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

[Impressions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/impressions)

Impressions

Track when an ad is rendered or visible to a user.

Impression tracking is fundamental for measuring ad visibility in VTEX Ads. This guide explains how to properly send impression events when your application displays advertisements to users.

## Impression event rules

* Impression events should be sent when an ad is rendered in the viewport.
* Each impression is deduplicated within a 1-minute window per user, per device, per ad.
* Impression events require both `user_id` and `session_id` for proper attribution.
* Impression URLs are unique to each ad and should be obtained from the [Get ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-ads-api%23post-/v1/rma/-publisher%5Fid-) response.

> 🚧 Don't construct event URLs manually. Always use the URL provided from the `POST` [Get ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-ads-api%23post-/v1/rma/-publisher%5Fid-) request.
>
> This is extremely important to ensure long-term stability of the integration, because the parameters of the event URL may change over time, but the integration itself does not.

## Sending an impression event

Use the `POST` [Track ad impressions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/vtex-ads-api%23post-/v1/beacon/impression/-ad%5Fid-) endpoint to send impression events. Check the endpoint documentation for detailed information about all available fields.

Request example:

`1

POST https://events.newtail-media.newtail.com.br/v1/beacon/impression/4a94bc6e-7db1-425f-8430-cb4d17488b3b?pos=1 HTTP/1.1

2

accept: application/json

3

content-type: application/json

4

5

{

6

 "user_id": "6f92d1e9-00b6-4f8b-9645-faeab321e1cc",

7

 "session_id": "5898b8d1-c250-4bb5-931b-8b9d0ee7b499"

8

}

`

Successful response example:

> A successful response will have HTTP code 202.

`1

{

2

 "messages": [

3

 "impression will be processed soon"

4

 ]

5

}

`

Failed response example:

> A failed response will have HTTP code 422\. The error message follows the [RFC 8927](https://read.calvincode.net/reader?url=https://datatracker.ietf.org/doc/rfc8927/) format

`1

[

2

 {

3

 "instancePath": "",

4

 "keyword": "required",

5

 "message": "must have required property 'user_id'",

6

 "params": { "missingProperty": "user_id" },

7

 "schemaPath": "#/anyOf/0/required"

8

 },

9

 {

10

 "instancePath": "",

11

 "keyword": "required",

12

 "message": "must have required property 'session_id'",

13

 "params": { "missingProperty": "session_id" },

14

 "schemaPath": "#/anyOf/1/required"

15

 },

16

 {

17

 "instancePath": "",

18

 "keyword": "anyOf",

19

 "message": "must match a schema in anyOf",

20

 "params": {},

21

 "schemaPath": "#/anyOf"

22

 }

23

]

`

Contributors

1

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

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 Ads/getting-started-with-vtex-ads-api/ads-events/impressions.md)

[Ads events notification« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions//docs/guides/ads-events-notification)[ViewsNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions//docs/guides/views)

Contributors

1

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

ON THIS PAGE

[Impression event rules](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/impressions%23impression-event-rules)

[Sending an impression event](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/impressions%23sending-an-impression-event)

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 Ads/getting-started-with-vtex-ads-api/ads-events/impressions.md)

Copy page

On this page

ON THIS PAGE

[Impression event rules](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/impressions%23impression-event-rules)

[Sending an impression event](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/impressions/docs/guides/impressions%23sending-an-impression-event)

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] Provide a guide on guides external seller integration connector 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/external-seller-integration-connector/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/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/external-seller-integration-connector/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/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/external-seller-integration-connector/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/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/external-seller-integration-connector/updates/release-notes)

Guides

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

---

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

---

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

---

Integration Guides

[Back office integration guide (ERP/PIM/WMS)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/erp-integration-guide)

[Customer Credit](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/customer-credit-integration-guide)

[External Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-marketplace-integration-guide)

[External Seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-guide)

[Marketplace / Seller architecture](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-architecture)

[Store setup for VTEX Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-vtex-marketplace-setup)

[External seller processing payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-processing-payments)

[External seller connector](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector)

[Catalog management for VTEX Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-vtex-marketplace-operation)

[Gift Card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/gift-card-integration-guide)

[Headless commerce](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/headless-commerce)

[Login (SSO)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/login-integration-guide)

[Punchout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/punchout)

[Offer Management Integration Guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/sent-offers-integration-guide-connectors)

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/payments-integration-guide)

[Search Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/search-integration-guide)

[Session Manager](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/session-manager)

[Tax Service](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/tax-service-integration-guide)

[Pricing Hub](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/pricing-hub)

[reCAPTCHA](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/recaptcha)

---

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

---

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

---

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

---

Payments

---

Orders

---

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/external-seller-integration-connector/docs/guides/activity-flow)

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides)

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

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

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

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

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/troubleshooting)

---

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

Guides

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

---

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

---

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

---

Integration Guides

[Back office integration guide (ERP/PIM/WMS)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/erp-integration-guide)

[Customer Credit](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/customer-credit-integration-guide)

[External Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-marketplace-integration-guide)

[External Seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-guide)

[Marketplace / Seller architecture](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-architecture)

[Store setup for VTEX Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-vtex-marketplace-setup)

[External seller processing payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-processing-payments)

[External seller connector](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector)

[Catalog management for VTEX Marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-vtex-marketplace-operation)

[Gift Card](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/gift-card-integration-guide)

[Headless commerce](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/headless-commerce)

[Login (SSO)](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/login-integration-guide)

[Punchout](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/punchout)

[Offer Management Integration Guide](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/sent-offers-integration-guide-connectors)

[Payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/payments-integration-guide)

[Search Protocol](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/search-integration-guide)

[Session Manager](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/session-manager)

[Tax Service](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/tax-service-integration-guide)

[Pricing Hub](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/pricing-hub)

[reCAPTCHA](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/recaptcha)

---

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

---

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

---

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

---

Payments

---

Orders

---

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/external-seller-integration-connector/docs/guides/activity-flow)

---

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

---

VTEX Session

---

VTEX Shield

---

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

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides)

Integration Guides

[External Seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-guide)

[External seller connector](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector)

External seller connector

The seller integration flow comprises eight different API requests. Four of these are calls that the seller should make to the marketplace. The other four are requests that the marketplace will need to make to the seller. So, for these, you will need to implement endpoints that are prepared to receive specific request bodies and respond with specific objects.

In the table below, you will find every API request needed for each step of the integration. Each one of them links to their specific API Reference documentation, where you can find the request URLs, methods, headers, the explanation of every field, and examples of requests and responses.

## Seller integration requests flow

| Step                                                                | API Request                                                                                | Request Target |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| [Catalog Notification](#catalog-notification)                       | post[Change Notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/catalog-api%23post-/api/catalog%5Fsystem/pvt/skuseller/changenotification/-skuId-)                | ➡ Marketplace  |
| [Catalog Registration](#catalog-registration)                       | put[Send SKU Suggestion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/marketplace-api%23manage-suggestions)                                                                     | ➡ Marketplace  |
| [Catalog and Storefront Update](#catalog-update)                    | post[Fulfillment Simulation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment%23post-/pvt/orderForms/simulationn)           | ⬅ Seller       |
| [Order Placement](#order-placement)                                 | post[Order Placement](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment%23post-/pvt/orders)                                  | ⬅ Seller       |
| [Order Dispatching](#order-dispatching)                             | post[Authorize Fulfillment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment%23post-/pvt/orders/-sellerOrderId-/fulfill)    | ⬅ Seller       |
| [Order Invoicing and Tracking](#order-invoicing)                    | post[Order Invoice Notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/oms/pvt/orders/-orderId-/invoice)                                   | ➡ Marketplace  |
| [Cancellation by the Marketplace](#cancellation-by-the-marketplace) | post[Marketplace Order Cancellation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment%23post-/pvt/orders/-orderId-/cancel)  | ⬅ Seller       |
| [Cancellation by the Seller](#cancellation-by-the-seller)           | post[Cancel Order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol%23post-/pvt/orders/-marketplaceOrderId-/cancel)                                     | ➡ Marketplace  |
| [Order invoicing](#order-invoicing)                                 | post[Send invoice](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol%23post-/pvt/orders/-marketplaceOrderId-/invoice)                                    | ➡ Marketplace  |
| [Send tracking information](#order-tracking)                        | post[Send tracking information](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol%23post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-)       | ➡ Marketplace  |
| [Update tracking status](#order-tracking)                           | post[Update tracking status](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol%23post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-/tracking) | ➡ Marketplace  |

> To help you test the integration requests and see in practice how they behave, we've assembled a Postman API Collection with all eight requests listed in this guide, including the necessary URLs, methods, headers, and example request bodies.\\n\\n[![{"base64":"  ","img":{"width":128,"height":32,"type":"svg","mime":"image/svg+xml","wUnits":"px","hUnits":"px","url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/Integration-Guides/external-seller-integration-guide/button_32.svg"}}](https://read.calvincode.net/reader?url=https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/Integration-Guides/external-seller-integration-guide/button_32.svg)](https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/external-seller-integration-connector-0.png)

Let’s walk through each of the steps in the integration.

## Catalog notification

The seller is responsible for suggesting new SKUs to be sold in the marketplace, as well as notifying the marketplace about updates to SKUs that already exist. Both scenarios begin with a catalog notification. To send this notification, the seller must call the `[POST ChangeNotification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/catalog-api%23post-/api/catalog_system/pvt/skuseller/changenotification/-skuId-)` endpoint provided by the marketplace.

Use the **Change Notification API** to notify the marketplace about changes in the **catalog information** of a SKU, such as:

* Name
* Description
* Images
* EAN
* Specifications

> For price and inventory change notification, please see the [Catalog Update](#catalog-update) section.

If the request is properly authenticated and formatted, there are two possible responses:

* **200 OK**: The SKU already exists in the marketplace. The seller should proceed to update its catalog information.
* **404 Not Found**: `"Seller StockKeepingUnit not found for this seller id"`
This means the SKU does not yet exist in the marketplace. The seller must first register the SKU offer before it can be updated.

The “status 404” response means that the SKU does not yet exist in the marketplace. In this case, in order to push the SKU offer to the marketplace, the seller should register the SKU.

The “status 200” response means that the SKU informed in the request already exists in the seller. In this case, the seller should _update_ the SKU information.

## Catalog registration

When the marketplace responds to the Change Notification request with status 404, it means that the SKU informed by the seller does not exist in the marketplace’s catalog. In this case, the seller should send an SKU offer to the marketplace.

> The catalog is owned by the marketplace, and the seller has no direct access to it. This is why every SKU is sent as an offer, which needs to be approved by the marketplace in order to become an SKU actually registered in the marketplace’s catalog.

The SKU offer is sent through the put[Send SKU Suggestion](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/marketplace-api%23manage-suggestions) API request. In this request, the seller informs mandatory information about the SKU, such as the product and SKU name, the seller ID, and the image URL.

> Don’t forget that, for the Save Suggestion request to work, the marketplace must have created the proper brands and categories in their account. This should be done in the setup phase of the integration.

Besides sending new SKU offers to the marketplace, the seller can update offers that have already been sent and have not yet been approved by the marketplace. To do this, you should make the same request used to create a new offer. In this case, the offer information will be replaced by the new one.

> An offer update only works if the original offer hasn’t yet been approved or disapproved by the marketplace. An approved offer ceases do exist, and the SKU registration that comes from it can only be edited by the marketplace.

## Catalog update

To notify the marketplace of price and inventory changes, the seller must call the following endpoints:

* [Notify marketplace of price update](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-apis%23post-/notificator/-sellerId-/changenotification/-skuId-/price)
* [Notify marketplace of inventory update](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-apis%23post-/notificator/-sellerId-/changenotification/-skuId-/inventory)

After these notifications, the marketplace will reach out to the seller to retrieve the latest SKU information.

### Endpoint implementation

The endpoint that the marketplace will call is the post[Fulfillment Simulation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment%23post-/pvt/orderForms/simulation) endpoint. The marketplace will send an object containing an array of items. The seller must use this list to get the updated information about the referred SKUs and send them back to the marketplace, following the response format explained in the API Reference.

Be mindful to add `/api` in your endpoint's base url for the call to function properly.

> This route directly impacts the marketplace checkout flow and is essential to the functioning of the integration. Because of that, it needs to have high performance and availability.

> The maximum time that VTEX marketplaces wait for a response from the fulfillment endpoint is 2.5 seconds. After that, the product will be considered unavailable or inactive.

## Storefront update

During the order flow, the marketplace storefront needs to be constantly fetching the updated price and inventory of each SKU in the cart. This is essential to guarantee that the customer will always be presented with the most updated information possible.

As in the [catalog update](#catalog-update) step, this information is provided by the seller through the post[Fulfillment Simulation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment%23post-/pvt/orderForms/simulation) endpoint. As in that step, the same request format should be expected and the same response format should be returned.

When the Fulfillment Simulation call is applied in the Storefront simulation scenario, the request from VTEX does not send the paramenters `country` and `postalCode`.

## Seller processing payments

If the seller is processing payments, once the [necessary configurations](https://read.calvincode.net/reader?url=https://developers.vtex.com/vtex-rest-api/docs/external-seller-processing-payments) are set up, the seller must send their VTEX account name to the marketplace.

You can find your account name in your VTEX environment by accessing **Account Settings > Account Management > Account**, and looking for the `Account Name` field.

This information will be added in the `merchantName` field in the [Storefront Update](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector%23storefront-update) and [Order Placement](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector%23order-placement) steps of the integration guide. This is the field that confirms that payments will be done on the seller's side:

`"merchantName": "sellerAccountName",`

## Order placement

Once the customer finishes their checkout, the marketplace needs to let the seller know there is a newly placed order.

### Endpoint implementation

The marketplace notifies the seller about a new order through the post[Order Placement](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment%23post-/pvt/orders) endpoint, which needs to be implemented by the seller.

The marketplace will send information such as the items contained in the cart, the client’s profile data, the shipping data, and the payment data. With that, the seller will be able to create the order in their own store.

## Order dispatching

After the payment is finished and approved, the marketplace sends a request to the seller to notify it that the fulfillment process can be started.

### Endpoint implementation

This notification is done through a request to the post[Authorize Fulfillment](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment%23post-/pvt/orders/-sellerOrderId-/fulfill) endpoint, which needs to be implemented by the seller.

The body of this request contains only one information: the `marketplaceOrderId`, which identifies the order in the marketplace. The seller should use this ID to trigger the fulfillment process.

## Order invoicing

Once the fulfillment process is triggered and the invoice is issued by the seller, the invoice data must be sent to the marketplace. The seller sends this information through the post[Order Invoice Notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/oms/pvt/orders/-orderId-/invoice) request.

## Order tracking

The same endpoint called by the seller to send the invoice is used to send the order tracking information, which holds the following fields:

* Carrier
* Tracking identifier
* Tracking URL

In this case, the post[Order Invoice Notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/orders-api%23post-/api/oms/pvt/orders/-orderId-/invoice) should happen once the seller delivers the package to the carrier and receives the tracking data from it.

## Cancellation by the marketplace

Order cancellations are never wanted, but they happen in every store. So the seller must be ready to receive order cancellation requests from the marketplace. For that, you will need to implement the last endpoint in this integration guide.

### Endpoint implementation

The post[Marketplace Order Cancellation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment%23post-/pvt/orders/-orderId-/cancel) endpoint must be implemented on the seller's side. This call should be made twice: once for the _Evaluate cancellation request_ scenario, and a second time to _Confirm cancellation_ or _Refuse cancellation_

For the seller to:

* **Evaluate a cancellation request:** it is possible to send an empty body as a response to the cancellation request, meaning that the seller is evaluating whether to proceed with the cancellation or not.
* **Confirm the cancellation request:** it is possible to confirm the order cancellation by the marketplace by responding to the call with a body including only one information: the `marketplaceOrderId`, which identifies the order in the marketplace. The seller should use this ID to trigger the cancellation of the corresponding order. The seller should then respond with the same `marketplaceOrderId` and also with the `orderId`, which identifies the order in the seller, the date and time of the notification receipt, and a protocol code that confirms the receipt of the request (which may have the value `null`).
* **Refuse a cancellation request:** it is possible to to [send the Invoice](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol%23post-/pvt/orders/-marketplaceOrderId-/invoice), meaning that the cancellation has been denied, and the flow continues to the [Order Invoicing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector%23order-invoicing) step, and the ones that follow it.

## Cancellation by the seller

On certain occasions, the seller may also need to cancel the order itself. This might happen, for example, if there’s a problem with the order that prevents the seller from fulfilling it. In this case, the seller must call the post[Cancel Order](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/marketplace-protocol%23post-/pvt/orders/-marketplaceOrderId-/cancel) endpoint.

> If the order status is `Invoiced`, the order can only be canceled if—before using the Cancel Order endpoint—the seller sends a return invoice.\\n\\nTo do this, you must use the Order Invoice Notification endpoint, explained in the [Order invoicing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector%23order-invoicing) session. To inform the system that you are sending a return invoice, you must use the value input for the field type of the request body.\\n\\nAfter doing this, you will be able to send a cancellation request for the invoiced order, by using the endpoint referenced below.

## Setting payment conditions

---

After building the endpoints listed in this guide and preparing your integration to send the requests expected by the marketplace, there is only one final configuration step before the VTEX marketplace can receive SKU offers from the external seller.

Contributors

4

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

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/_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/external-seller-integration-connector/_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/external-seller-integration-connector/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7108339%3Fv%3D4%26w=64%26q=75)](https://github.com/brunoamui)

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/Integration-Guides/external-seller-integration-guide/external-seller-integration-connector.md)

[External seller processing payments« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector//docs/guides/external-seller-processing-payments)[Catalog management for VTEX MarketplaceNext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector//docs/guides/external-seller-integration-vtex-marketplace-operation)

Contributors

4

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

[![Photo of the contributor](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/_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/external-seller-integration-connector/_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/external-seller-integration-connector/_next/image?url=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F7108339%3Fv%3D4%26w=64%26q=75)](https://github.com/brunoamui)

ON THIS PAGE

[Seller integration requests flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23seller-integration-requests-flow)

[Catalog notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23catalog-notification)

[Catalog registration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23catalog-registration)

[Catalog update](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23catalog-update)

[Endpoint implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23endpoint-implementation)

[Storefront update](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23storefront-update)

[Seller processing payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23seller-processing-payments)

[Order placement](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23order-placement)

[Endpoint implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23endpoint-implementation)

[Order dispatching](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23order-dispatching)

[Endpoint implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23endpoint-implementation)

[Order invoicing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23order-invoicing)

[Order tracking](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23order-tracking)

[Cancellation by the marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23cancellation-by-the-marketplace)

[Endpoint implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23endpoint-implementation)

[Cancellation by the seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23cancellation-by-the-seller)

[Setting payment conditions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23setting-payment-conditions)

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/Integration-Guides/external-seller-integration-guide/external-seller-integration-connector.md)

Copy page

On this page

ON THIS PAGE

[Seller integration requests flow](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23seller-integration-requests-flow)

[Catalog notification](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23catalog-notification)

[Catalog registration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23catalog-registration)

[Catalog update](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23catalog-update)

[Endpoint implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23endpoint-implementation)

[Storefront update](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23storefront-update)

[Seller processing payments](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23seller-processing-payments)

[Order placement](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23order-placement)

[Endpoint implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23endpoint-implementation)

[Order dispatching](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23order-dispatching)

[Endpoint implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23endpoint-implementation)

[Order invoicing](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23order-invoicing)

[Order tracking](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23order-tracking)

[Cancellation by the marketplace](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23cancellation-by-the-marketplace)

[Endpoint implementation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23endpoint-implementation)

[Cancellation by the seller](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23cancellation-by-the-seller)

[Setting payment conditions](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/external-seller-integration-connector/docs/guides/external-seller-integration-connector%23setting-payment-conditions)

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 apps vtexbr.tiktok tbp 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/vtexbr.tiktok-tbp/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/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/vtexbr.tiktok-tbp/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/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/vtexbr.tiktok-tbp/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/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/vtexbr.tiktok-tbp/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/vtex-io-deprecated-apps)

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides)

[API Reference](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/api-reference)

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/storefront-development)

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

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/updates/release-notes)

VTEX IO Apps

[Basic components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/basic-components)

---

[Store Components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/store-components)

---

[Advanced components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/advanced-components)

---

[B2B components](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/b2b-components)

---

[B2B Suite](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/apps/vtex.b2b-suite)

---

[Functional Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/functional-apps)

---

[Layout Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/layout-apps)

---

[Pixel Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/pixel-apps)

---

[My Account - StoreV2 version](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/apps/vtex.my-account)

---

[VTEX IO deprecated apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/guides/vtex-io-deprecated-apps)

---

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

TikTok for Business

Community extension

Version: 1.6.2

Latest version: 1.6.2

> This app is no longer maintained by VTEX. This means support and maintenance are no longer provided.

> �The integration with TikTok is available only for stores in _Brazil_.

The TikTok for Business app allows merchants to easily connect their stores to TikTok, using it as a channel to drive sales and market products sold in their ecommerce.

The app includes the following features:

* Connecting TikTok For Business and Ads Manager accounts with your VTEX account.
* Syncing products in your catalog with TikTok.
* Inserting the [TikTok Pixel](#tiktok-pixel) in your store.
* Managing TikTok Ads from the VTEX Admin.

## Before you start

Before installing the app, make sure you have read about its compatibility and requirements in the following sections.

### Compatibility

TikTok for Business is fully compatible with stores using [VTEX IO](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/cms--2YcpgIljVaLVQYMzxQbc3z/4yB9wSl79cArd68aRBnBZ2) and partially compatible with stores using [Legacy CMS](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/cms--2YcpgIljVaLVQYMzxQbc3z/1oN446gRGcR2s70RvBCAmj) or [Headless CMS](https://read.calvincode.net/reader?url=https://faststore.dev/tutorials/cms/0%23vtex-headless-cms).

In VTEX IO stores, installing and configuring TikTok for Business causes the TikTok Pixel to be inserted automatically. On the other hand, stores using the Legacy CMS or Headless CMS need to configure the TikTok Pixel manually. Refer to the [Manual TikTok Pixel configuration](#manual-tiktok-pixel-configuration) section for more information on this.

### Requirements

To be able to configure the TikTok for Business app in your VTEX store, you need to meet the following requirements:

* Having a [TikTok Business account](https://read.calvincode.net/reader?url=https://ads.tiktok.com/help/article?aid=13288).
* Having [Admin permission](https://read.calvincode.net/reader?url=https://ads.tiktok.com/help/article?aid=238947046829056266%26lang=en) in TikTok Business Center.
* Having a [TikTok Ads Manager account](https://read.calvincode.net/reader?url=https://ads.tiktok.com/help/article?aid=9678) linked to your business account.

## Installation

You can install TikTok for Business on the [VTEX App Store](https://read.calvincode.net/reader?url=https://apps.vtex.com/).

After installation, the app settings will be available in the VTEX Admin, under **Marketplace > TikTok**. For some versions of the VTEX Admin, the page can be found at **Apps > My Apps > TikTok**.

## Configuration

You must configure the TikTok for Business app through the VTEX Admin. Please check out the documentation about the [Integration with TikTok](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/tiktok-integration--1r0yJSO11nrer1YVu3WTFd/7Dwfwu1aHMp1aR1yvej5nv) for instructions on this process.

In case you are using the Legacy CMS or Headless CMS, you need to configure the TikTok Pixel manually as well. Read the following sections for more information on this.

## TikTok Pixel

The TikTok Pixel is a JavaScript code snippet that you can include on your store's website, which allows you to track various actions of your websites visitors and share them with TikTok. These actions are called Pixel events  see the [Supported Pixel events](#supported-pixel-events) section to learn more.

In VTEX IO stores, the TikTok Pixel is automatically inserted when you install and configure TikTok for Business. In Legacy CMS or Headless CMS stores, you need to configure it manually. Refer to the [Manual TikTok Pixel configuration](#manual-tiktok-pixel-configuration) section for more information on this.

### Supported Pixel events

TikTok Pixel supports the following events:

| **Event**      | **Description**                              |
| -------------- | -------------------------------------------- |
| 'ViewContent'  | When a visitor views any page in your store. |
| 'AddToCart'    | When a visitor adds a product to the cart.   |
| 'PlaceAnOrder' | When a visitor places an order.              |

For more information on TikTok Pixel events, read TikToks documentation on [Standard Events and Parameters](https://read.calvincode.net/reader?url=https://ads.tiktok.com/help/article?aid=10028%26lang=en).

### Manual TikTok Pixel configuration

> � This configuration applies only to [Legacy CMS](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/cms--2YcpgIljVaLVQYMzxQbc3z/1oN446gRGcR2s70RvBCAmj) and [Headless CMS](https://read.calvincode.net/reader?url=https://faststore.dev/tutorials/cms/0%23vtex-headless-cms) stores. If your store is built with [VTEX IO](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/cms--2YcpgIljVaLVQYMzxQbc3z/4yB9wSl79cArd68aRBnBZ2), skip this section.

To insert the TikTok Pixel manually, you must follow the instructions in the TikTok documentation, more specifically in [Option 2: Install the pixel using Developer Mode](https://read.calvincode.net/reader?url=https://ads.tiktok.com/help/article?aid=10000357%23:~:text=to%20create%20events.%C2%A0-,Option%202%3A%20Install%20the%20pixel%20using%20Developer%20Mode%C2%A0,-Step%201%3A%20Install) of the [Get Started with Google Tag Manager](https://read.calvincode.net/reader?url=https://ads.tiktok.com/help/article?aid=10000357%23:~:text=TikTok%20Pixel%20Partners.-,Get%20Started%20with%20Google%20Tag%20Manager,-There%20are%20two) guide.

## Disconnecting from TikTok

Merchants can disable the integration between their store and TikTok at any time, by following the instructions on [Disconnecting TikTok from your store](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/tiktok-integration--1r0yJSO11nrer1YVu3WTFd/24SfBYkRkKMaetgjLDKgaP%23disconnecting-tiktok-from-your-store).

In case their TikTok user access token is revoked (deactivated or invalid), the integration will be disconnected automatically. The `access_token` is the token that bears the authorization of the TikTok user.

Once disconnected, your integration with TikTok stops completely: the TikTok Pixel and the integration with your store's catalog are deactivated. Therefore, you will no longer be able to send new products to TikTok and update products on the TikTok catalog automatically.

On the other hand, existing products are not deleted from the TikTok catalog by VTEX, which means they continue to appear on TikTok. For this to stop, you need to manually delete the products in [TikTok Catalog Manager](https://read.calvincode.net/reader?url=https://ads.tiktok.com/help/article?aid=10001005).

After disconnecting, it is possible to reactivate the integration at any time by repeating the steps described in [Configuring the integration with TikTok for Business in the VTEX Admin](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tracks/tiktok-integration--1r0yJSO11nrer1YVu3WTFd/4AEUg7pEdX1beOaQhFf0wC).

**Upcoming documentation:**

* [Feature/error toast](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/tiktok-tbp/pull/88)
* [Feature/brpa 1305 update register account](https://read.calvincode.net/reader?url=https://github.com/vtex-apps/tiktok-tbp/pull/89)

See also

[VTEX App StoreVTEX IO Apps](https://read.calvincode.net/reader?url=https://apps.vtex.com/)

ON THIS PAGE

[Before you start](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/apps/vtexbr.tiktok-tbp%23before-you-start)

[Compatibility](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/apps/vtexbr.tiktok-tbp%23compatibility)[Requirements](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/apps/vtexbr.tiktok-tbp%23requirements)

[Installation](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/apps/vtexbr.tiktok-tbp%23installation)

[Configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/apps/vtexbr.tiktok-tbp%23configuration)

[TikTok Pixel](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/apps/vtexbr.tiktok-tbp%23tiktok-pixel)

[Supported Pixel events](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/apps/vtexbr.tiktok-tbp%23supported-pixel-events)[Manual TikTok Pixel configuration](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/apps/vtexbr.tiktok-tbp%23manual-tiktok-pixel-configuration)

[Disconnecting from TikTok](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/apps/vtexbr.tiktok-tbp/docs/apps/vtexbr.tiktok-tbp%23disconnecting-from-tiktok)

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 search and scroll api queries 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/search-and-scroll-api-queries/docs/guides)

[API ReferenceExplore detailed information about our endpoints.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/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/search-and-scroll-api-queries/docs/app-development)

[Storefront DevelopmentExpress your brand identity creating unique storefronts.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/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/search-and-scroll-api-queries/docs/vtex-io-apps)

[TroubleshootingFind practical solutions to common development issues.](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/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/search-and-scroll-api-queries/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/vtex-platform-overview)

---

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

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/catalog-integration)

---

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

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/master-data)

[Understanding Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/understanding-master-data)

[Master Data best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/master-data-best-practices)

[Extracting data from Master Data with search and scroll](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/extracting-data-from-master-data-with-search-and-scroll)

[Pagination in the Master Data API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/pagination-in-the-master-data-api)

[Avoiding CORS in Master Data requests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/avoiding-cors-in-master-data-requests)

[Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/master-data-v2)

[Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/master-data-v1)

---

Payments

---

Orders

---

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/search-and-scroll-api-queries/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides)

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

[App Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/app-development)

[Storefront Development](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/storefront-development)

[VTEX IO Apps](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/vtex-io-apps)

[Troubleshooting](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/troubleshooting)

---

[Release Notes](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/updates/release-notes)

Guides

[VTEX Platform Overview](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/vtex-platform-overview)

---

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

---

[Getting started](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/getting-started)

---

Integration Guides

---

[Catalog](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/catalog-integration)

---

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

---

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/master-data)

[Understanding Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/understanding-master-data)

[Master Data best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/master-data-best-practices)

[Extracting data from Master Data with search and scroll](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/extracting-data-from-master-data-with-search-and-scroll)

[Pagination in the Master Data API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/pagination-in-the-master-data-api)

[Avoiding CORS in Master Data requests](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/avoiding-cors-in-master-data-requests)

[Master Data v2](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/master-data-v2)

[Master Data v1](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/master-data-v1)

---

Payments

---

Orders

---

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/search-and-scroll-api-queries/docs/guides/activity-flow)

---

[VTEX Ads](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/vtex-ads)

---

VTEX Session

---

VTEX Shield

---

[Data Protection Plus](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/data-protection-plus)

---

Weni by VTEX

---

[Guides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides)

[Master Data](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/master-data)

[Master Data best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/master-data-best-practices)

[Extracting data from Master Data with search and scroll](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/extracting-data-from-master-data-with-search-and-scroll)

Extracting data from Master Data with search and scroll

Learn how to extract data from Master Data using the search and scroll endpoints and best practices for optimizing queries and handling large datasets.

In this guide, you will learn how to extract data from Master Data using the search and scroll endpoints, including when to use each route, how to optimize queries, and best practices.

> In Master Data v1, you can export data directly from the interface. See [Exporting data from Master Data v1](https://read.calvincode.net/reader?url=https://help.vtex.com/en/tutorial/exporting-data--tutorials%5F1125) for more information.

## Search

The search route is ideal when you need to find a specific set of documents within your store. It is particularly useful for paginated queries, where you want to retrieve up to 10,000 documents in small chunks over multiple requests and each page is limited to 100 documents.

> When paginating, the `_sort` parameter is recommended. The API does not guarantee a specific order by default. Therefore, omitting the `_sort` parameter may lead to duplicate documents or return unexpected pages.

Check the search endpoint reference for your Master Data version:

* [Master Data API v1 - Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/masterdata-api%23get-/api/dataentities/-acronym-/search)
* [Master Data API v2 - Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/master-data-api-v2%23get-/api/dataentities/-dataEntityName-/search)

### Best practices

When using the search endpoint, these best practices will help optimize your data retrieval process:

* **Apply filters to narrow your search**: Improve performance by reducing the number of documents returned. This speeds up the query and ensures that your requests are more efficient.
* **Use exact values for queries instead of wildcards (`*`):** Heavy usage of wildcards may be subject to temporary blocks.
* **Avoid large datasets:** If you are querying many documents, break your query into smaller intervals.

> Learn more about [Search pagination in the Master Data API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api%23search-pagination).

## Scroll

The scroll route is designed for extensive data retrieval, especially when integrating Master Data with external systems. It is the best choice if you need to query the entire database or deal with over 10,000 documents.

Check the scroll endpoint reference for your Master Data version:

* [Master Data API v1 - Scroll](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/masterdata-api%23get-/api/dataentities/-acronym-/scroll)
* [Master Data API v2 - Scroll](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/api-reference/master-data-api-v2%23get-/api/dataentities/-dataEntityName-/scroll)

Your first scroll request will return a token in the `X-VTEX-MD-TOKEN` response header. Submit this value in the `_token` query parameter for your next requests until you receive an empty list, which indicates that all documents have been retrieved.

> Learn more about [Scroll pagination in the Master Data API](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/pagination-in-the-master-data-api%23scroll-pagination).

### Scroll best practices

To ensure efficient and reliable data retrieval, follow these strategies when using the scroll endpoint:

* **Implement filters to divide the request into smaller batches:** This reduces the likelihood of timeouts. For example, you might filter by created date and process data month by month. Smaller batches are also easier to reprocess if a timeout occurs, making your operation more resilient.
* **Run up to 10 scrolls simultaneously per account:** Limiting the number of parallel scrolls helps prevent errors and timeouts. By using filters to create smaller batches and parallelizing these batches in a controlled manner, you can speed up data retrieval while reducing the risk of overloading the account.

> **Scroll behavior and limitations**
>
> * **Each scroll operation allows only one query for the duration of the token.** This means that you cannot change a scroll’s query by changing parameters after the first request. You can navigate pages of the original first request until the token expires, or initiate other scrolls (up to 10 simultaneously).
> * If Master Data stops receiving requests with the scroll `X-VTEX-MD-TOKEN` token, it will expire in **20 minutes**. After that, you can make new scroll requests, limited to 10 simultaneous scrolls.
> * The maximum number of documents per scroll request is **1,000**.

Contributors

1

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

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/Master-Data/master-data-best-practices/extracting-data-from-master-data-with-search-and-scroll.md)

[Master Data best practices« Previous](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries//docs/guides/master-data-best-practices)[Pagination in the Master Data APINext »](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries//docs/guides/pagination-in-the-master-data-api)

See also

[Pagination in the Master Data APIGuides](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/pagination-in-the-master-data-api)

Contributors

1

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

ON THIS PAGE

[Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/extracting-data-from-master-data-with-search-and-scroll%23search)

[Best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/extracting-data-from-master-data-with-search-and-scroll%23best-practices)

[Scroll](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/extracting-data-from-master-data-with-search-and-scroll%23scroll)

[Scroll best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/extracting-data-from-master-data-with-search-and-scroll%23scroll-best-practices)

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/Master-Data/master-data-best-practices/extracting-data-from-master-data-with-search-and-scroll.md)

Copy page

On this page

ON THIS PAGE

[Search](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/extracting-data-from-master-data-with-search-and-scroll%23search)

[Best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/extracting-data-from-master-data-with-search-and-scroll%23best-practices)

[Scroll](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/extracting-data-from-master-data-with-search-and-scroll%23scroll)

[Scroll best practices](https://read.calvincode.net/reader?url=https://developers.vtex.com/docs/guides/search-and-scroll-api-queries/docs/guides/extracting-data-from-master-data-with-search-and-scroll%23scroll-best-practices)

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=)