Import via feed

A product feed allows you to share your catalog with Topsort, synchronize data and maintain up-to-date auction listings.

During the integration process you can provide us with the url of your product feed and we will ensure that your catalog remains up to date.

Our platform supports several formats:

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

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.

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	-	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	no	Slug of vendor name	ID of the vendor of this product.
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/or vendors. See the section below.

Example TSV

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

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/or 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 IDs

It’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.