A product feed is a file containing a marketplace's product information. They are typically used to display product listings on a site and move product data from one place to another. In this case, you're pushing your product information to Topsort's sandbox environment.

The Product Feed method allows you to share products, vendors and categories through one or more files. This method is more manual and helpful for quick experimentation or for smaller marketplaces.

How the Product Feed method works

You share a catalog or list of all your products either through 1 JSON file or a TSV file. The catalog should include information such as product ID, product name, product description, vendor ID, vendor name, stock, price, product image, category ID and category name.

If there are any updates on the catalog, you can share a new product feed with Topsort and Topsort will automatically update changes to be reflected on the dashboard.

How do we get the files

  • You can give us a URL and authentication header for the files. We'll fetch them periodically and update the catalog on our side.
  • You then upload the files to Topsort through the manager. In this case it is up to you to reupload the file(s) when your catalog changes.

How to format the data

You can format your data as either a JSON file or a TSV file and send it to us to implement.

Option 1: one single JSON file

The structure must be the following:

interface Catalog {
 products: Product[];
 categories: Category[];
 vendors: Vendor[];
}

interface Product {
 id: string;
 name: string;
 description?: string;
 vendors: string[]; // list of vendor ids
 brand: Brand;
 categories: string[]; // list of category ids
 price: number;
 imageURL: string;
}

interface Brand {
 id: string;
 name: string;
}

interface Category {
 id: string;
 name: string;
 parentId?: string; // optional, defines a category hierarchy when present
}

interface Vendor {
 id: string;
 name: string;
}

Example with 2 products, one category, one vendor, and one brand:

{
  products: [
    {
      "id": "wv93m",
      "name": "Coca Cola 350ml can",
      "description": "blah",
      "vendors": ["34c50"],
      "brand": {
        "id": "0w984",
        "name": "Coca Cola"
      },
      "categories": ["x20t8"],
      "price": 1.39,
      "imageURL": "https://your.cdn.com/path/to/the/product-image"
    },
    {
      "id": "3j49i",
      "name": "Dr. Pepper 350ml can",
      "description": "blah",
      "vendors": ["34c50"],
      "brand": {
        "id": "g534j",
        "name": "Keurig"
      },
      "categories": ["x20t8"],
      "price": 1.29,
      "imageURL": "https://your.cdn.com/path/to/the/other-product-image"
    }
  ],
  categories: [
    {
      "id": "mv2u0",
      "name": "Drinks"
    },
    {
      "id": "x20t8",
      "name": "Drinks/Fizzy Drinks",
      "parentId": "mv2u0"
    }
  ],
  vendors: [
    {
      "id": "34c50",
      "name": "Vendor Company"
    }
  ]
}

Option 2: three TSV files following the structure above, one for vendors, one for categories, one for products. TSVs cannot be nested, so there are some concessions to do if this route is taken:

  • The brand field is replaced by brandId and BrandName columns.
  • vendor and category ids are separated by commas.

The same example above would be represented like the following content, stored as a TSV file. We display them as tables for illustrative purposes.

products.tsv:

idnamedescriptionvendorbrandIdbrandNamecategorypriceimageURL
wv93mCoca Cola 350ml canblah34c500w984Coca Colax20t81.39https://your.cdn.com/path/to/the/product-image
3j49iDr. Pepper 350ml canblah34c50g534jKeurigx20t81.29https://your.cdn.com/path/to/the/other-product-image

categories.tsv:

idnameparentId
mv2u0Drinks
x20t8Drinks/Fizzy Drinksmv2u0

vendors.tsv:

idname
34c50Vendor Company