Skip to content
Toposort Logo
ad-platform

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. In this section, we will cover the steps to integrate Topsort with VTEX using the VTEX IO Toolbelt. This integration is composed by the following apps:

  • Catalog Integration
  • Auctions Integration (Sponsored Listings)
  • 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. Please note that the VTEX IO apps don’t support automatic updates.

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 (check the section API Token and Devlogs for more details).

Open your terminal and log in to your VTEX account:

Terminal window
vtex login {YOUR_ACCOUNT_NAME}

Setting up Your API Key

We created the Topsort Services Settings app inside VTEX (topsortpartnercl.services), which provides an endpoint with the pre-configured API Key in an encrypted way. To setup topsortpartnercl.services you need to follow these steps:

  1. Install topsortpartnercl.services using:

    Terminal window
    vtex install topsortpartnercl.services

  2. Set the API-Key for topsortpartnercl.services:

    • Go to the admin of your VTEX Workspace.
    • Go to App > App Management and find the services app:
    Topsort Services
    • Click on settings and add the API Key, then click on Save.

You can verify the installation by going to {{workspace__url}}/_v/ts/settings and checking out if the endpoint returns an encrypted hash. Other apps will access this endpoint to authorize to Topsort when making a request.

Importing Catalog into Topsort

The Catalog Integration app listens for catalog changes in your VTEX store and synchronizes them with Topsort. Whenever a SKU is added or updated, the app sends the catalog data to Topsort, ensuring that your ads reflect the most current catalog.

  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.

    Topsort Apps

  4. Click on the app to open its settings.

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

  6. Click on Save.

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.

    Topsort Apps

  4. Click on the app to open its settings.

  5. Optionally, you can also type the Topsort Number of Sponsored Slots. This parameter refers to the number of winners returned by Topsort on the auction response.

  6. Click on Save.

Tracking Events

The Events Integration app tracks user interactions within the promoted products 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.

  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 Events Integration.

    Topsort Apps