Start your content search
6 min read

Connect your VTEX catalog to Empathy Platform

The Empathy Platform Feed connector is a VTEX IO app that synchronizes your VTEX product catalog with Empathy Platform. Once installed, the Feed connector sends your VTEX catalog data as a feed to the Empathy Platform search ecosystem, keeps it up to date through automatic updates, and supports regionalized search for stores that use white-label franchises.

This guide walks you through installing and configuring the Feed connector app, setting up automatic updates, and activating regionalization.

Steps to getting started with the Feed connector
  1. Install the Feed connector
  2. Set up the Feed connector affiliate
  3. Configure the Feed connector
  4. Index the VTEX product catalog

warning

This app is maintained separately from the core Empathy Platform product. Steps and configuration options may vary in later versions of the app. Always check the original VTEX app documentation (opens new window) for the most up-to-date information.

Before you begin

Make sure you have the following before installing the Feed connector:

  • A VTEX store account with admin access.
  • The instance ID for your Empathy Platform environment. You can find it in the Empathy Platform Playboard's Instance Management Console (IMC) (top right corner).
  • The Empathy Platform API credentials for your account. If you haven't received them, ask your Empathy Platform key account manager or partner.
  • Access to your VTEX admin panel.
  • VTEX Toolbelt CLI (opens new window) installed and authenticated against your VTEX account if you want to install the app using the command line.

Installing and configuring the connector

This section covers the end-to-end setup of the Feed connector to synchronize your VTEX product catalog with Empathy Platform.

Installing the Feed connector app

You can install the Feed connector app in two ways:

  • Command line: Authenticate into your VTEX account and run the install command using the VTEX Toolbelt CLI:
vtex login {your-account-name}
vtex install empathymx.empathy-feed-connector
  • Browser: Go to https://{your-account-name}.myvtex.com/admin/apps/empathymx.empathy-feed-connector/setup and select Install.

The installation process starts. It may take some minutes to complete.

Setting up the Feed connector affiliate

The Feed connector uses a VTEX affiliate to receive real-time product, price, and inventory updates.

Once the Feed connector installation is complete, you need to create a VTEX affiliate to identify Empathy Platform as an affiliate. An affiliate acts as a webhook that will notify Empathy Platform about changes made to an SKU's information, changes in inventory, or updates in pricing.

To create a VTEX affiliate for Empathy Platform, perform the following steps:

  1. Go to Store Settings > Orders > Settings in your VTEX admin panel.

    New affiliate

  2. Select + New Affiliate in the Affiliates tab.

  3. Complete the affiliate details in the configuration window: affiliate name and identifier, the number of the sales channels to define the catalog assortment and prices, and your email address to receive notifications about the integration.

    Affiliate details

  4. Enter the following URL https://{your-account-name}.myvtex.com/_v/empathy/skuUpdate in the Search endpoint field. Replace {your-account-name} with your VTEX account name.

  5. Set the Search endpoint version to the default option 1.x.x..

  6. Leave Use my payment method unchecked.

  7. Select Save to finish the configuration process.

The affiliate for Empathy Platform is now active. Next, you need to configure the Feed connector for it to be ready for receiving product, inventory, and price updates.

Configuring the Feed connector

Configure the Feed connector to connect your VTEX store to the Empathy Platform Index service and define the environment where product catalog data is sent. Perform the following steps:

  1. Go to Catalog > Empathy connector in your VTEX admin panel.
  2. Select Edit configuration under Empathy settings.
  3. Select the environment: staging for development or production for your live environment.
  4. Provide the Empathy Platform Index API credentials to connect to the Index service. Contact your Key Account Manager, if you haven't been provided with them.
  5. Enter the instance ID assigned to your VTEX commerce store in Empathy Platform.
  6. Select Save.

Instance ID

To find your Instance ID, go to Empathy Platfrom Playboard > Instance Management. You locate the ID avobe the right-side menu.

Running a full feed indexing

After setting up and configuring the Feed connector, you can upload your VTEX product catalog to the Empathy Platform Index service for the first time. This way, all your product catalog data converts into a feed file compatible with the Empathy Platform Search service.

To index your VTEX product catalog to Empathy Platform, perform the following steps:

  1. Go to Catalog > Empathy connector in your VTEX admin panel.
  2. Select Full update.

A full indexing of your product catalog starts. It may take some minutes depending on the number of SKUs in your store. Check the Considerations callout below for more information on indexing times.

Considerations

When running a full indexing, take into account the following considerations:

  • A full index update takes around 5 minutes per 1,000 SKUs.
  • A full index update can run once per hour only.
  • Full index updates may take some minutes for the changes to appear in search results.

Setting up automatic feed updates

Turn on automatic feed updates to keep your VTEX product catalog synced with Empathy Platform. Perform the following steps:

  1. Go to Catalog > Empathy connector in your VTEX admin panel.
  2. Select the Edit configuration button in the Automatic updates section.
  3. Turn on Automatic updates.
  4. Set the update frequency. The minimum interval is 5 minutes.
  5. Set the number of retries in case an update fails.
  6. Select Save.

note

Once automatic feed updates are active, keep these times in mind:

  • Inventory changes: up to 5 minutes.
  • Price or product information changes: from 5 to 15 minutes.

Bulk catalog imports

Automatic feed updates are designed for incremental changes and may not capture all updates from a bulk catalog import reliably. If you import a large number of products at once, run a full update from Catalog > Empathy connector in your VTEX admin panel afterward to make sure all changes are sent to the Empathy Platform Index service.

Turn on regionalization

Regionalization refers to scoping search results, including product availability and pricing, to a specific geographic delivery zone. The Empathy Platform Feed connector supports this by integrating with VTEX white-label franchises, where each franchise covers a distinct zone. This feature requires that your regionalization strategy maps each coverage area to a single white-label franchise, one franchise per zone.

To turn on regionalization, follow these steps for each white-label enviroment:

  1. Install the Feed connector app.
  2. Set up the Feed connector affiliate in each white-label environment. Make sure the Search endpoint URL points to the white-label account you're configuring, not the main account.
  3. Go to Catalog > Empathy connector > Empathy settings in your VTEX admin panel.
  4. Turn on Enable regionalization.
  5. Select Save.
  6. Run a full update from the main environment to send the VTEX product catalog data to the Empathy Platform Index service with the white-label variations included.

Next steps

Your VTEX catalog is now connected to Empathy Platform. Continue with Inject the Empathy search widget into your VTEX store to set up the frontend search experience for your shoppers.

coding tip

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

Cookie-Less