Skip to content
guides

Integrating Topsort with VTEX

If you use VTEX as your e-commerce platform, you can integrate Topsort directly into your VTEX store to offer ad placements to your vendors or sellers.

We cover the full Topsort integration cycle with VTEX (see Integration Overview), but it is not mandatory to set up all three integrations exclusively with VTEX. This means you can set up one or two integrations, depending on your integration path discussed with your Topsort integration engineer.

Nonetheless, in this section we will cover the steps to integrate Topsort with VTEX using the VTEX IO Toolbelt. This integration is composed of 3 apps:

  1. Catalog Integration
  2. Auctions Integration (Sponsored Listings)
  3. Events Integration

These apps work together to synchronize your catalog with Topsort, display sponsored products in search results, and track user interactions for reporting and optimization.

Getting Started

Prerequisites

Before you begin, ensure you have the following:

  • A VTEX account with administrative access.
  • The VTEX IO Toolbelt installed and configured.
  • A Topsort account with a Marketplace API Key and an Advanced API Key. You can create these in your Topsort dashboard under Settings > API Integration. (see Authentication Guide for more details).
  • Open your terminal and log in to your VTEX account:
Terminal window
vtex login {YOUR_ACCOUNT_NAME}

Replace {YOUR_ACCOUNT_NAME} with your VTEX account name.

Catalog Integration

The Catalog Integration app listens for catalog changes in your VTEX store and synchronizes them with Topsort. Whenever a SKU is added or updated, category is modified, brand is deleted, the app sends the updated product data to Topsort, ensuring that your ad placements reflect the most current information.

  1. Install the Catalog Integration app:

    Terminal window
    vtex install topsortpartnercl.catalog@1.x
  2. Confirm the app installation by running:

    Terminal window
    vtex ls

    You should see topsortpartnercl.catalog listed among the installed apps.

  3. Access the VTEX Admin portal, navigate to Apps > My Apps, and find Topsort’s Catalog Integration.

  4. Click on the app to open its settings.

  5. Enter your Topsort Advanced API Key in the topsortAPIKey field.

  6. Optionally, you can check the box to also check on Sync product variants (not recommended)

  7. Click on Save.

Auctions Integration Steps (sponsored listings)

The Auctions Integration is built on top of VTEX’s search resolver, including sponsored products in the search results. After fetching the organic results, it sends them to Topsort’s Auctions API to determine the auction winners. The winning sponsored products are then placed at the top of the search results, followed by the organic results.

  1. Install the Auction Integration app:

    Terminal window
    vtex install topsortpartnercl.auctions@1.x
  2. Confirm the app installation by running:

    Terminal window
    vtex ls

    You should see topsortpartnercl.auctions listed among the installed apps.

  3. Access the VTEX Admin portal, navigate to Apps > My Apps, and find Topsort’s Auctions Integration.

  4. Click on the app to open its settings.

  5. Enter your Topsort Marketplace API Key.

  6. Optionally, you can also type the Topsort Number of Sponsored Slots

  7. Click on Save.

Events Integration Steps

The Events Integration app tracks user interactions within your store and sends this data to Topsort. It captures key events such as:

  • Impressions: When a user sees a promoted product in a listing page (PLP) or section.
  • Clicks: When a user clicks on a promoted product or adds it to the cart.
  • Purchases: When an order is completed and confirmed to be successful.

This data is crucial for optimizing ad performance and reporting.

  1. Install the Events Integration app:

    Terminal window
    vtex install topsortpartnercl.events@1.x
  2. Confirm the app installation by running:

    Terminal window
    vtex ls

    You should see topsortpartnercl.events listed among the installed apps.

  3. Access the VTEX Admin portal, navigate to Apps > My Apps, and find Topsort’s Catalog Integration.

  4. Click on the app to open its settings.

  5. Enter your Topsort Marketplace API Key.

  6. Click on Save.

What’s next?

The VTEX IO apps don’t support automatic updates, so you will need to update the apps manually whenever a new version is released. Kindly keep an eye on the apps pages:

Whenever the app is outdated, you should see a notification similar to this:

If you have any questions or need assistance with the integration, feel free to contact us at support@topsort.com.