Docs

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 decimalDiscounts or promotional pricing for a productfalse
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 catalogfalse
catlevel2Name text The second level of products. Denotes hierarchy of products on your catalogfalse
catlevel3Name text The third level of products. Denotes hierarchy of products on your catalogfalse
catlevel4Name text The fourth level of products. Denotes hierarchy of products on your catalogfalse
category text Denotes the name of the hierarchy of a producttrue
subCategory text Denotes the name of the second level of the hierarchy of the producttrue
color text Specifies the available colors for a producttrue
size text Specifies the available sizes for a producttrue
availability bool Specifies the product’s inventory statusfalse
description longText Is the detailed account of the salient aspects, characteristics or features of a productfalse
imageUrl link Link to image librarytrue
productUrl linkLink to the Product Detail Page (PDP) of a productfalse
brand text Distinctive name or label of the manufacturer of the productfalse
price decimal The amount of money a customer pays for a productfalse
title text Short or summarized description of a product. Precedes the descriptionfalse
gender text Denotes availability of the product for the two sexesfalse
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 merchandisefalse
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 catalogfalse
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:

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.

Next Steps