Getting started with VTEX integration

Bring Empathy Platform's search and discovery experience to your VTEX commerce store:

• Learn more about the VTEX integration and its capabilities
• Discover the integration ecosystem and how the components interact
• Connect your VTEX catalog to the Empathy Platform Index service
• Inject the Empathy search widget into your VTEX storefront

The VTEX integration

Integrating Empathy Platform into a VTEX commerce store is a two-step process that covers both the catalog data layer and the search UI layer.

The catalog data layer connects your VTEX product catalog to the Empathy Platform Index service, keeping your search results up to date with your store's inventory, pricing, and product information. The UI layer injects the Empathy Platform Interface X search widget into your VTEX storefront, wiring it up to your store's cart, wishlist, and analytics.

Once integrated, shoppers enjoy AI-assisted search and discovery features such as Related Prompts, AI Carousels, AI-powered Related Tags, and Next Queries. Search experiences that guide shoppers through your catalog intuitively and help them find what they're looking for faster. At the same time, merchants and analysts can fine-tune search relevance and analyze search performance directly from the Empathy Platform Playboard, with no-code controls and real-time analytics.

Which capabilities does Empathy Platform integration provide?

Besides, the integration provides the following capabilities out of the box:

• Full catalog indexing: sends your entire VTEX product catalog to the Empathy Platform Index service on demand.
• Real-time updates: receives product, price, and inventory changes from VTEX automatically via a webhook affiliate, keeping your search results in sync with your store data.
• Scheduled automatic updates: runs incremental catalog updates on a configurable schedule, with a minimum interval of 5 minutes.
• Regionalized search: scopes search results, including product availability and pricing, to specific geographic delivery zones using VTEX white-label franchises.
• Search UI injection: loads the Interface X search widget into your VTEX storefront via VTEX Pixel, without modifying your store theme directly.
• Cart and wishlist integration: wires shopper interactions in the search UI to your store's cart and wishlist.
• Analytics event tracking: sends custom Google Analytics 4 (GA4) events for every cart and wishlist interaction triggered from search results.

For a complete overview of what Empathy Platform offers, see Search and discovery features and Discover the Playboard.

note

This integration is maintained separately from the core Empathy Platform product. Always check the Empathy Platform Pixel app repository (opens new window) and the VTEX Developer Portal (opens new window) (in Spanish) for the most up-to-date information on each app.

The integration ecosystem

The VTEX integration involves two VTEX IO apps and several Empathy Platform and VTEX services working together. Understanding how they interact helps you set up and troubleshoot the integration more effectively.

The Feed connector app installs in your VTEX account and creates a VTEX affiliate, which is a webhook that notifies Empathy Platform every time a product, price, or inventory change occurs in your store. These updates are forwarded to the Empathy Platform Index service, which processes and stores the catalog data in a format optimized for search. The connector also supports on-demand full catalog uploads and scheduled incremental updates.

The Pixel app runs as a private VTEX IO app scoped to your account. It injects the Empathy Platform Interface X search widget into your storefront via VTEX Pixel, loads the Empathy search script from the Empathy CDN, and connects shopper search interactions such as cart additions, wishlist updates, and analytics events, back to your store's VTEX services.

Check a detailed view of the backend data flow and component architecture (opens new window) (in Spanish).

Connecting your VTEX catalog to Empathy Platform

The first step in the VTEX integration process is to synchronize your VTEX product catalog with the Empathy Platform Index service using the Empathy Platform Feed connector, a VTEX IO app that sends your catalog data to Empathy Platform as a feed and keeps it up to date through automatic incremental updates. It also supports regionalized search for stores that use VTEX white-label franchises.

To start the integration process, see Connect your VTEX catalog to Empathy Platform.

Injecting the Empathy search widget into your VTEX store

Once your catalog is connected, the second step is to inject the Empathy Platform Interface X search widget into your VTEX storefront using the Empathy Platform Pixel app. This VTEX IO app loads the search UI via VTEX Pixel and wires it up to your store's cart, wishlist, and GA4 analytics, without modifying your store theme directly.

To continue with the integration process, check Inject the Empathy search widget into your VTEX store.

coding tip

Before going live, run through the pre-launch checklist to make sure the Feed connector and Empathy Platform Pixel app are correctly set up.

coding tip

If something isn't working as expected, check the VTEX integration troubleshooting for a full list of common issues before going live.