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 bybrandId
andBrandName
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:
id | name | description | vendor | brandId | brandName | category | price | imageURL |
---|---|---|---|---|---|---|---|---|
wv93m | Coca Cola 350ml can | blah | 34c50 | 0w984 | Coca Cola | x20t8 | 1.39 | https://your.cdn.com/path/to/the/product-image |
3j49i | Dr. Pepper 350ml can | blah | 34c50 | g534j | Keurig | x20t8 | 1.29 | https://your.cdn.com/path/to/the/other-product-image |
categories.tsv:
id | name | parentId |
---|---|---|
mv2u0 | Drinks | |
x20t8 | Drinks/Fizzy Drinks | mv2u0 |
vendors.tsv:
id | name |
---|---|
34c50 | Vendor Company |