Importing a product catalog feed is a premium feature. Contact your Customer Success Manager to enable it on your Kameleoon Account.
- With an XML file containing all required metadata for each of your products. Use this method if you don’t have a data layer and your catalog contains less than 50,000 products. You can easily choose the frequency Kameleoon should sync your catalog in the store settings page. You should perform an XML import once every 24-72 hours to update Kameleoon with your product stock.
- With a Google Merchant Feed URL. Use this method if you have already uploaded your product in Google Merchant Center and if your catalog contains less than 50,000 products. Contact your Kameleoon Customer Success Manager to enable this method. Follow these steps to sync the Google Merchant with Kameleoon.
- Via Kameleoon’s REST API. Utilize Kameleoon’s REST API for updating your catalog if you need regular updates, especially when dealing with products that quickly go out of stock due to limited availability.
- Via Kameleoon’s Product API. You should use this method if you have a data layer that contains detailed information about your products and product categories. Working with Kameleoon’s API requires that you have metadata available for products and categories from your product pages (for example, in a data layer) that Kameleoon can read and feed into Kameleoon’s product recommendation algorithms.
Kameleoon will automatically mark all products not present in the feed as out of stock. Thus, to enhance the feed processing speed and reduce its size, Kameleoon recommends excluding out-of-stock products from your feed.It’s important to note that one drawback of the Product API method is that if visitors don’t actively search for or browse products, Kameleoon may not be aware of those products, and Kameleoon may not propose them in product recommendation blocks.
Syncing your product feed using Kameleoon Product API
The Product API powers Kameleoon’s product recommendation algorithms and social proofing messaging, such as product impressions and purchases counters and advanced targeting conditions. Once you enable Kameleoon’s Product API methods on your website, Kameleoon will start sending product detail events whenever your visitors browse a product or category page, add a product to their carts, or make a purchase. It will also enable the collection of statistics about a given product (for example, the number of times visitors purchased or viewed it in the last hour or day) and power the creation of audience groups you can use in the segment builder using predefined product targeting criteria. You’ll need to add the Product page, Category page, Cart page, and Thank you page snippets to your source code to track interactions with your products and inform the Product Recommendations algorithm. You can also inject them by using the Global custom script on your project’s Scripts tab.trackProductView()
Use thetrackProductView() method on product pages to track when a visitor views a product. For details, see the trackProductView() method reference.
Ensure you provide all necessary data for your social proofing setup. You can retrieve only the data sent via the
trackProductView() method through the obtainProductData() endpoint.trackCategoryView()
Use thetrackCategoryView() method on category pages to track when a visitor views a product category. For details, see the trackCategoryView() method reference.
Ensure the category ID used here matches the one sent with the trackProductView() method. For details, see the Category object reference.
trackAddToCart()
Use thetrackAddToCart() method on any page where a visitor can add a product to their cart (for example, the home page, product page, category page, or cart page).
For details, see the trackAddToCart() method reference.
trackTransaction()
Use thetrackTransaction() method on any page displayed after a visitor completes a purchase or transaction. For details, see the trackTransaction() method reference.
Kameleoon syncs your whole product catalog every 2 hours and will automatically tag out of stock products as “unavailable” every 12 hours. Kameleoon considers a product unavailable when the
availableQuantity attribute passed with the addProductView method is equal to zero, which ensures that Kameleoon’s product recommendations only include products that are in stock. You can also set a product to be out of stock using the availableQuantity attribute when using the addProductView method.Syncing your product feed using an XML file
Syncing your product catalog using an XML file includes the following steps:- Create an XML file with all the required metadata for each of your products, categories, and locations (for example, countries or locations where you operate and have different pricing, stock, or details for your products). The file must be available from a distant URL. Ensure that you host it in a secure area (for example, S3 bucket) that’s accessible to Kameleoon.
- Sync the XML file with Kameleoon and choose the update interval that suits your needs (for example, every hour, 3 hours, 6 hours)
- Track your visitors’ events.
Multiple languages websites aren’t supported. You must create a separate project for each language and provide one feed for each.
Whitelist the following IP addresses to ensure a seamless image download process:
95.216.99.81/2695.216.99.220/2695.216.23.145/2695.216.10.183/2695.216.114.218/2695.217.32.105/2695.216.4.144/2695.216.102.29/26
Step 1: Creating your product feed
The product feed must include basic information about your catalog. Refer to the tables below for the mandatory attributes you must include.Element : yml_catalog
Element : yml_catalog > shop
Element : yml_catalog > shop > categories
Thecategories element contains a list of category elements. Each product category you use to group or tag your products has its own category element.
Example:
Element : yml_catalog > shop > locations
Thelocations element contains a list of your store locations. Each location has its own location element.
You can use the following attributes for the element locations:
Example:
Element : yml_catalog > shop > offers
Theoffers element contains your list of products. Each product has its own offer element.
If all variants of one product are available from the same URL in your store, and there is no common identifier for product variants, Kameleoon will choose the cheapest product variant when recommending this product to your visitors. The availability flag in this case should fit into the following logic: if at least one product variant is in stock, then Kameleoon considers the product in stock.
Element : yml_catalog > shop > offers > offer
You can use the following attributes for theoffer element:
The offer element can take the following tags:
Example:
Element : yml_catalog > shop > offers > offer > locations
Thelocations element contains a list of locations, and the availability and price of the current product in these locations. Each location has its own element location within the offer tag.
You can use the following attributes for the locations element:
Kameleoon considers the product available for purchase only in the locations listed in the offer element. In all other unlisted locations, Kameleoon considers the product out of stock. You don’t need to add locations if your product is available in all locations, as Kameleoon will automatically consider the product in-stock in all of them.
locations element can take the following tags (only required if the product has a different price/stock quantity in some of your locations).
Element : yml_catalog > shop > offers > offer > fashion
Use the fashion tag if you sell clothes products. The fashion element can take the following tags:Don’t specify the
gender element if it’s irrelevant. Kameleoon labels the product “unisex” and gives it a lower recommendation priority than other products of the same gender.type element can take the following values:
Example:
You must set the
type parameter when using the sizes parameter. You can add a list of available sizes by adding as many size tags as needed within the sizes element (see example below). If you have several locations, and the availability of product sizes is different across locations, insert a location tag with the list of available sizes in each size element (see example below).
Example:
One product can have multiple colors available. You can set a specific picture for a color by adding a
picture attribute. Otherwise, Kameleoon displays the primary picture.Element : yml_catalog > shop > offers > offer > auto
Use theauto tag if you sell auto parts and accessories. Kameleoon’s algorithm automatically recognizes a potential buyer with certain characteristics such as the brand and model of the car. The algorithm then displays parts and accessories in recommendation blocks that are only compatible with specific car brands and models.
The auto element contains a list of compatible cars. Each car brand and model has its own compatibility element.
If the product is compatible with all cars, you don’t need to add
compatibility elements. If the product is compatible with all car models of a brand, you don’t have to add the model attribute.compatibility element:
If the product is only compatible with a list of cars, you can also add a
vds element for each compatible car. The vds contains the Vehicle Identification Number (VIN) that serves as the car’s fingerprint.
Example:
Element : yml_catalog > shop > offers > offer > tags
Thetags element contains a list of tags associated with the product. Tags improve Kameleoon’s search engine recommendation. Each value has its own tag element.
You will find examples of XML files you can use as a template below:
- XML product feed - example 1 (without locations elements):
- XML product feed - example 2 (with locations elements):
Step 2: Sync your product feed file with Kameleoon
By default, the Kameleoon feed syncs with your XML file every 24 hours. However, you can change this setting if your product catalog updates more frequently. You can make adjustments in Store settings.

Step 3: Track visitors’ events
In addition to syncing your XML product feed, you must implement events to track product events, such as product view, add to cart, and transaction.Product views
You must use thetrackProductView method.
Kameleoon.API.Products.trackProductView("ProductID/SKU/EAN");
Read the detailed instructions
trackAddToCart()
You must use thetrackAddToCart() method whenever a visitor adds a product to their cart or when the visitor accesses the cart page.
Kameleoon.API.Products.trackAddToCart("ProductID/SKU/EAN");
Read the detailed instructions
Transaction
trackTransaction() instructions
Validate your feed sync status
If you use Kameleoon’s Product API, you can verify that your implementation was successful by using theobtainProductData method. This method allows you to easily QA your implementation in real-time and verify that Kameleoon collected your product attributes correctly.
You can visualize your product catalog by using the Data feed menu.


FAQ
How do I decide between XML import and API import for my catalog?
How do I decide between XML import and API import for my catalog?
Base your decision on your catalog size and technical infrastructure. Use the XML import method if your catalog contains fewer than 50,000 products and you lack a website data layer. If your catalog exceeds 50,000 products, use the Product Recommendation API.If you already uploaded your products to Google Merchant Center and your catalog contains fewer than 50,000 products, you can sync with a Google Merchant Feed URL instead. Contact your Customer Success Manager to enable this method.
Which attributes can I import from Google Merchant Center versus Kameleoon XML?
Which attributes can I import from Google Merchant Center versus Kameleoon XML?
Supported attributes depend on your feed format. Google Merchant Center feeds and Kameleoon XML feeds differ for custom labels and stock quantity.Custom labels (
custom_label_0 through custom_label_4)Kameleoon doesn’t support these attributes. The recommendation module doesn’t import custom_label attributes from Google Merchant Center feeds, so you can’t use these fields for filtering or display.Stock quantity- Google Merchant feeds: Not supported. The Google product data specification doesn’t include a numerical stock count (only “availability” status), so you can’t import exact inventory numbers through Google CSV or XML feeds.
- Kameleoon XML: Supported. To use exact stock counts, use the native Kameleoon XML format and populate the
stock_quantityfield. - Viewing and using stock data: If you import stock data through Kameleoon XML, the values appear in the Data feed overview. Use the stock quantity attribute to create filters, for example to include only products with more than 5 units in stock.
Why is the recommended product count much lower than my total product stock?
Why is the recommended product count much lower than my total product stock?
The Popular and Trending algorithms have strict data quality requirements. If the number of products available to these algorithms is much lower than your total product stock, Kameleoon has filtered out products that aren’t eligible for recommendations. Kameleoon labels eligible products Widgetable.For a product to be widgetable, you must set up and import all four required fields:
- Price
- Name
- URL
- Picture (the image URL must be valid and retrievable)
- Click Settings > Recommendations > Products > Data feed.
- Select False from the Widgetable dropdown.
- Click a product to view its attributes. Kameleoon highlights the issue, such as a missing price or a failed image retrieval, in the product’s attribute list.
Why can't Kameleoon download my product images?
Why can't Kameleoon download my product images?
A common reason a product isn’t widgetable is that Kameleoon couldn’t download its image during catalog synchronization. Without an image, Kameleoon excludes the product from the Popular and Trending algorithms. If a product has a valid image URL but still lacks a picture, your shop’s server configuration might cause the issue:
- Server overload: Your shop’s storage or server can’t handle the volume of requests from Kameleoon. Kameleoon downloads images using 50 simultaneous threads, which often causes timeout errors.
- Security blocking: Your firewall or anti-DDoS protection might block requests based on the user agent or IP address.
- User agent: Kameleoon downloads images using the user agent
Kameleoon Fetcher 2.0. If downloads fail, allow this user agent in your server settings. - IP address: Allow all Kameleoon cluster IP addresses to keep access uninterrupted. See the list of IP addresses.
- User agent: Kameleoon downloads images using the user agent