Skip to main content
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

NameRequiredDefaultDescription
idyes-Unique identifier for each product.
activenotrueWhether the product can be part of campaigns or auctions. Inactive products will be removed from existing campaigns.
titleyes-Name of the product
category.0.nameyes-Category name of the primary category for this product.
category.0.idnoSlug of category nameID of the primary category for this product.
vendor.0.nameyes 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.idyes if not use seller_nameSlug of vendor nameID of the vendor of this product.
seller_nameyes if not use vendor.0.nameVendor name of the product, same value as vendor.0.name.
google_product_categoryyesCategories provided in Google Taxonomy Format.
priceno-Product price.
image_linkno-URL to an image of the product.
availabilityno-Stock status. Must be one of in stock, out of stock or preorder.
descriptionno-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": "apparal-and-accessories",
    "name": "Apparel & Accessories"
  },
  {
    "id": "clothing",
    "name": "Clothing",
    "parentId": "apparal-accessories"
  },
  {
    "id": "dresses",
    "name": "Dresses",
    "parentId": "clothing"
  }
]

​
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.