Prepare Catalog
The catalog file contains a list of all your products and its attributes. Once you've uploaded your catalog, it becomes the feed that powers our search solution on your eCommerce site.
On this page, we define what a catalog and its attributes are, how you can send your updated catalog file to us and some practices we recommend you follow while prepping your catalog for upload.
Overview
A catalog powers the content in an eCommerce site and contains attributes that describe properties of the product in more detail.
Some generic attributes considered universal across businesses are:
- uniqueID (required)
- title
- price
- description
- category
- imageURL
- productURL
- currency
- brand
- color
- price
- availability
Broadly, the typical feed will contain many other attributes, which will have display, searchable, merchandisable, and unique attributes.
Here's how a sample feed file without variants would appear
{
"feed": {
"catalog": {
"add": {
"items": [
{
"uniqueId": "ss10010",
"title": "Short Sleeve Shirt",
"description": "Get the perfect look for the summer."
},
{
"uniqueId": "ss11023",
"title": "Relaxed Fit Jeans",
"description": "Jeans for all seasons."
}
]
}
}
}
}
Click here to view a sample feed file with variants.
Searchable attributes
Searchable attributes are attributes that optimize your search results. Whilst there could be 100s of attributes that define a product, we index only the attributes you mark as searchable.
In other words, searchable attributes are those attributes which are used to search when shoppers type in a query. Products displayed will have attributes that are relevant to the search query.
You can select these attributes within the Console (Merchandising > Query Rule).

Fields
Besides searchable and display attributes, products within your catalog file must have a Unique ID as well.
Unique Identifier
A unique identifier for every product irrespective of their attributes. Also known as a Stock Keeping Unit (SKU) or a productID (pid), these attributes help you track and maintain your store's inventory.
These attributes are not visible to shoppers.
There are two additional types of attributes we require:
- Feature Fields
- Custom Fields
Read more about Fields and how you can map fields.
Feature Fields
Feature fields are a list of predefined Unbxd attributes and can differ by business. Like generic fields, feature fields power product discovery on your web page.
In most cases, you do not have to define the schema for these fields, however, when the feature field does not match with the corresponding field within your product feed, you can define the schema by the dataType of that field.
For example, if you have the field 'amount' that indicates the price of the product, you can map the field 'amount' to 'price' and not have to redefine the schema.
In another example, if the "size" field in your catalog has data type "decimal" instead of text, the schema for the "size" field has to be defined in the product feed. Similarly, if the "gender" field in your catalog is "multivalue=true" instead of false, the schema for the "gender" field would need to be defined before the product attribute data in the Product Feed.
Any changes you make to the schema of a feature field will overwrite the default schema of that field.
Field Name | Data Type | Description | Multivalue |
---|---|---|---|
uniqueId* | text | Unique identifier of a product. It cannot have special character except '-' and '_' | false |
discount | decimal | Discounts or promotional pricing for a product | false |
rating | decimal | Unique identifier of a product. It cannot have special character except '-' and '_' | false |
currency | text | Unique identifier of a product. It cannot have special character except '-' and '_' | false |
catlevel1Name | text | Level of products. Denotes hierarchy of products on your catalog | false |
catlevel2Name | text | The second level of products. Denotes hierarchy of products on your catalog | false |
catlevel3Name | text | The third level of products. Denotes hierarchy of products on your catalog | false |
catlevel4Name | text | The fourth level of products. Denotes hierarchy of products on your catalog | false |
category | text | Denotes the name of the hierarchy of a product | true |
subCategory | text | Denotes the name of the second level of the hierarchy of the product | true |
color | text | Specifies the available colors for a product | true |
size | text | Specifies the available sizes for a product | true |
availability | bool | Specifies the product’s inventory status | false |
description | longText | Is the detailed account of the salient aspects, characteristics or features of a product | false |
imageUrl | link | Link to image library | true |
productUrl | link | Link to the Product Detail Page (PDP) of a product | false |
brand | text | Distinctive name or label of the manufacturer of the product | false |
price | decimal | The amount of money a customer pays for a product | false |
title | text | Short or summarized description of a product. Precedes the description | false |
gender | text | Denotes availability of the product for the two sexes | false |
skus | skus | Stock Keeping Unit (sku) is a number assigned to a product by a retail store to identify the price, product options and manufacturer of the merchandise | false |
variantID | text | Unique identifier of a variant, if any. It cannot have special character except ‘-’ and ‘_’. Note: It needs to be unique across entire product catalog | false |
variants | text | Field holding all the variants for a product | true |
categoryPath* | path | The category hierarchy a product belongs to. Different values present need to be separated using “>”. For example, “Men>Shoes>Casual Shoes” | true |
categoryPathID | text | The category comprises of names and IDs, a product belongs to.Different values present need to be separated using “>”. IDs and Names need to be separated using “|”.
For example, “cat100|Home>cat101|Luggage & Travel Accessories>cat102|Travel Accessories” | true |
sellingPrice | decimal | The amount of money at which a product or service is sold.
This amount includes retailer margins and excludes any discounts or promotions.
| false |
Fields that do not match with those of the predefined fields are not searchable.
Custom Fields
Attributes that are not part of our list of Feature Fields but part of your product catalog are known as Custom Fields. These attributes and their properties are included in your schema.
Like Feature fields, our search engines use these attributes to power product discovery on your web page.
Variants
Variants are products that share the same SKU or productID (PID) but have atleast two or more fields, like color, size, pattern that are different from the other fields of the same PID. These products will be displayed as a distinct product in the search results page.
Once your catalog has updated information related to variants, you can configure to display variants in a way that best suits your business vertical.
In each of the illustrations below, variants are configured to appear differently.
In the illustration below, the HDMI cable has 5 variants - color, size, gauge, quantity, and output.
In the illustration below, the product 'Mango Badam' has 1 variant - size. The PLP chooses to display the product as two separate entities here.
In this illustration, the skirt has two variants - color and size. The other fields like title, description, fabric/material, price are the same.
Upload
A product catalog may have multiple feed files, however to power your eCommerce search, we need your unified product feed file as a JSON file.
Three types of upload:
Three methods of upload:
- Rest APIs: Use our custom REST APIs to upload your feed.
- Secure File Transfer Protocol: Upload your feed through an SFTP.
- Platform Extensions: Use our custom platform extensions to upload your feed.
Best Practices
To ensure your feed is uploaded and integrated seamlessly, here are some practices we recommend:
- Ensure every product has the associated uniqueId.
- Ensure all attributes are defined in the schema.
- Ensure your catalog file is in JSON format.
- Field names are case-sensitive.
- Field names should start with alphabets or underscore. It can be alphanumeric, can have hyphens and underscores. It cannot contain special characters, spaces in between words, or end with an underscore.
- Do not send fields that have null values.