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

This method of associated keywords in search queries to form a meaningful phrase from the query to show relevant search results that match the intent of the shopper is called Named-Entity Recognition (NER). Know More

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

Feature Fields can be used without defining it in the schema. If you have a similar field, you can either map it to the corresponding feature field from the Console or define it in the schema.

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.