Product Feed

A product feed allows you to share your catalog with Topsort, synchronize data and maintain campaigns up-to-date. During the integration process you can provide us with the url of your product feed and we will ensure your catalog remains up to date. Our platform supports several formats:

Google Product Data Specification.
Tab separated values (TSV).
Comma separated values (CSV).

Topsort fetches data from a product feed

If your product catalog is already on a third-party platform like Algolia or VTEX, we can integrate directly with them for updates and synchronization, ensuring the product information is accurate. For detailed instructions on setting up these connections and specific requirements for each platform, please refer to the “3rd Party Integrations - Partners” section of our documentation.

Google Product Data Specification

Share your catalog with Topsort using existing Google product feeds. We support the Google Product Data Specification.

TSV and CSV

We support sharing your catalog using TSV and CSV feeds. The instructions in this section apply to both formats.

Which format should you use?We recommend you use TSV over CSV. CSV is more error prone due to commas often being present in the catalog data.If your product name or category name contains commas, you must use TSV.

Supported Columns

Name	Required	Default	Description
`id`	yes	-	Unique identifier for each product.
`active`	no	true	Whether the product can be part of campaigns or auctions. Inactive products will be removed from existing campaigns.
`title`	yes	-	Name of the product
`category.0.name`	yes	-	Category name of the primary category for this product.
`category.0.id`	no	Slug of category name	ID of the primary category for this product.
`vendor.0.name`	yes if not use `seller_name`	-	Vendor of the product. This is the entity that has their own budget to advertise this product and competes with other vendors.
`vendor.0.id`	yes if not use `seller_name`	Slug of vendor name	ID of the vendor of this product.
`seller_name`	yes if not use `vendor.0.name`		Vendor name of the product, same value as `vendor.0.name`.
`google_product_category`	yes	Categories provided in Google Taxonomy Format.
`price`	no	-	Product price.
`image_link`	no	-	URL to an image of the product.
`availability`	no	-	Stock status. Must be one of `in stock`, `out of stock` or `preorder`.
`description`	no	-	Detailed description of the product.

Categories can be provided in several ways. But only one is required. You can associate a product with more categories and vendors. See the section below.

File examples

Example TSV using vendor.0.name

id	name	description	vendor.0.id	vendor.0.name	vendor.0.image_link	category.0.id	category.0.name	category.1.id	category.1.name	image_link	price	availability
1293	Green Mask	Green Mask for removing imperfections, use during night or day	1710000087	Derma Laboratories		10000087	Skin Care	61	Beauty & Health	https://i.postimg.cc/0QxMWmbd/shampoo.png	23935.29	out of stock
1302	Cleanser Gel	N/A	17829100	Shiny Laboratories		10000087	Skin care			https://i.postimg.cc/0QxMWmbd/shampoo.png	16050.42	in stock

Example CSV using vendor.0.name

id,name,description,vendor.0.id,vendor.0.name,vendor.0.image_link,category.0.id,category.0.name,category.1.id,category.1.name,image_link,price,availability
1293,Green Mask,"Green Mask for removing imperfections, use during night or day",1710000087,Derma Laboratories,,10000087,Skin Care,61,Beauty & Health,https://i.postimg.cc/0QxMWmbd/shampoo.png,23935.29,out of stock
1302,Cleanser Gel,N/A,17829100,Shiny Laboratories,,10000087,Skin care,,,https://i.postimg.cc/0QxMWmbd/shampoo.png,16050.42,in stock

Multiple categories and vendors

Products can be associated with multiple categories and/or vendors. As you might have noticed, the category and vendor columns contain indices. You can add additional category and/or vendor columns as long as you increase the index appropriately. For example, a product with three categories and two vendors would have at the very least these columns:

category.0.id
category.1.id
category.2.id
vendor.0.id
vendor.1.id

Google Taxonomy Format

Alternatively, you can use Google’s Taxonomy Format as category names. This allows you to describe more complex hierarchical relationships. For example, this hierarchy:

Apparel & Accessories > Clothing > Dresses

Will result in three categories:

[
  {
    "id": "apparel-and-accessories",
    "name": "Apparel & Accessories",
    "path": "apparel_and_accessories"
  },
  {
    "id": "clothing",
    "name": "Clothing",
    "path": "apparel_and_accessories.clothing",
    "parentId": "apparel-and-accessories"
  },
  {
    "id": "dresses",
    "name": "Dresses",
    "path": "apparel_and_accessories.clothing.dresses",
    "parentId": "clothing"
  }
]

The path field is preferred for new integrations. The parentId field remains fully supported — there are no plans to remove it.

Hosting your product feed

Your product feed needs to be continuously accessible to Topsort so that we can keep our data up to date. We can currently access public product feeds or feeds that are protected using Basic HTTP Authorization. In addition, use the ETag Response headers to help us determine if a product feed has been updated since last fetch.

Deleting products

Products can be “soft deleted” by setting the active property to false. This can be done both via the API and via the product feed. Inactive products will not be included in new campaigns or auctions and will be removed from any active campaigns they are part of. To permanently delete products from Topsort’s system, use the API.

Generated slugs

When categories or vendors don’t have an ID, we generate one on the fly.

Prefer to use explicit IDsIt’s recommended to provide the IDs explicitly in your product feed, these IDs are used as references when managing campaigns and auctions.If you use generated IDs you will need to use the same algorithm on the marketplace side to create such references.

These IDs use a slug derived from the name. A slug is a kebab case formatted string that is suitable for inclusion in URLs. For example, Hello world becomes hello-world. The format is based on the npm slugify library.

Dev Tools

Marketplaces that send their catalog via a product feed can open Dev Tools > Catalog in the marketplace Admin Dashboard to monitor ingestion health without opening a support ticket. The Catalog tab surfaces key sync metrics at a glance:

Last sync time: when the most recent catalog sync ran
Average sync duration: how long syncs typically take
Success rate: across the last 14 runs
Recent sync runs: each ingestion with how many records were processed or skipped

With this view, engineering teams can confirm feeds are running on schedule and quickly spot failures or skipped-heavy runs.

Overview

Ad Platform

Ad Server

Toppie

Advanced Integrations

API

Google Product Data Specification

TSV and CSV

Supported Columns

File examples

Example TSV using vendor.0.name

Example CSV using vendor.0.name

Multiple categories and vendors

Google Taxonomy Format

Hosting your product feed

Deleting products

Generated slugs

Dev Tools

​Google Product Data Specification

​TSV and CSV

​Supported Columns

​File examples

​Example TSV using vendor.0.name

​Example CSV using vendor.0.name

​Multiple categories and vendors

​Google Taxonomy Format

​Hosting your product feed

​Deleting products

​Generated slugs

​Dev Tools

Google Product Data Specification

TSV and CSV

Supported Columns

File examples

Example TSV using vendor.0.name

Example CSV using vendor.0.name

Multiple categories and vendors

Google Taxonomy Format

Hosting your product feed

Deleting products

Generated slugs

Dev Tools