guides

VTEX XML Catalog Integration

The VTEX XML Catalog Integration allows you to synchronize your VTEX product catalog with Topsort using XML feed templates. This integration provides a flexible way to import your product data, including details like SKUs, categories, brands, pricing, and product variants.

Overview

This integration works by:

Creating an XML template in your VTEX Admin that defines your product data structure
Generating an XML feed URL that Topsort can periodically fetch
Processing the XML data to synchronize your products with Topsort’s advertising platform

Getting Started

Prerequisites

Before you begin, ensure you have:

Access to your VTEX Admin panel
Administrative permissions to create and manage XML templates
A Collection created with all products you want to include in the XML feed (follow this guide to set it up)
Your Topsort Advanced API Key (contact your Topsort representative if you don’t have this)

Integration Steps

Create the XML Template in VTEX Admin
Navigate to Store Settings > Channels > XML Integration in your VTEX Admin and access the XML template creation section. You’ll need to create a template that outputs your product data in the required XML format.
Configure Product Data Fields
Set up your XML template to include the following product information:
- Product ID
- Product title/name
- Description
- Product type/category path
- Brand
- Department
- Category
- Subcategory
- SKU reference code
- EAN/barcode
- Product link/URL
- Main image URL
- Price

Set Up XML Feed Structure

As a suggestion, you can use the following template as a format:

<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <entry>
    <id>product-id</id>
    <title>Product Name</title>
    <description>Product description</description>
    <productType>Category &gt; Subcategory</productType>
    <brand>Brand Name</brand>
    <skuReferenceCode>SKU123</skuReferenceCode>
    <ean>1234567890123</ean>
    <link>https://store.com/product-url</link>
    <imageLink>https://store.com/image.jpg</imageLink>
    <price>99.99</price>
  </entry>
  <!-- Additional products... -->
</feed>

Generate and Test the XML Feed URL
Once configured, the product feed can take up to 2 hours to get updated within the XML as per VTEX documentation. After that, test the public URL for the XML feed to ensure it generates the expected XML output.
The public URL is: https://{your-workspace-name}.vtexcommercestable.com.br/XMLData/{name-of-the-xml-from-previous-step}.xml
Configure Topsort Integration
Contact your Topsort representative to configure the XML feed integration. You’ll need to provide:
- Your XML feed URL
- Your Topsort Advanced API Key
- Any specific scheduling requirements for data synchronization
Validate the Integration
After setup, verify that your products are appearing correctly in your Topsort dashboard and that all product information is being imported as expected.

XML Template Configuration in VTEX Admin

To create the XML template in your VTEX Admin:

Access Store Settings
In your VTEX Admin, navigate to Store Settings > Channels > XML Integration.
Create New Template
Look for the XML template or feed template section and create a new template.
Configure Essential Settings
Configure these three essential settings as shown in the screenshot below:
- Select collection with all products: Choose the collection you created in the prerequisites
- Select to include inactive products: Check “Show out-of-stock (sold-out) SKUs in the results” to include inactive products
- Write the field names and check the required boxes: For each field (like Product ID), write the tag name and check the “Show Content” box next to it
Configure Template Fields
Map your VTEX product fields to the required XML structure. Ensure all mandatory fields are included:
- Product ID (required)
- Title (required)
- Brand (required)
- Image URL (required)
- Price (required)
Set Template Parameters
Configure any filters or parameters such as:
- Product availability status
- Category restrictions
- Brand filters
- Price range limits
Test and Publish
Test your template to ensure it generates valid XML output, then publish it to make the feed URL available.

Best Practices

Regular Updates: Ensure your XML feed reflects real-time inventory and pricing changes
Data Quality: Validate that all required fields are populated for optimal ad performance
Image URLs: Use high-quality, publicly accessible image URLs
Category Structure: Maintain consistent category hierarchies using ” > ” separators (e.g., “Electronics > Mobile Phones > Smartphones”)
Performance: Consider feed size and generation time for large catalogs

Troubleshooting

XML Feed Not Accessible: Verify that your XML template is published and the URL is publicly accessible.

Missing Products: Check that your template filters aren’t excluding products unintentionally.

Data Formatting Issues: Ensure special characters are properly encoded and price formats use decimal notation.

Category Mapping: Verify that category paths follow the expected format with proper separators.

Support

If you have any questions or need assistance with the XML template setup, contact us at support@topsort.com or reach out to your Topsort integration specialist.