Once you have your site key, you’re ready to upload your product catalog. A product catalog is a detailed list of products and their characteristics in a store.

This page walks you through the process of understanding what a schema and a catalog is, what and how you’ll need to upload both to seamlessly integrate them with our search solution.

Prepare Schema

Prepare Catalog

Upload Feed

TIP: Customers using Magento 2, Shopify, and Hybris can use our platform plugin to upload their feed and integrate Analytics.

Prepare Schema

A schema establishes the properties of each attribute within a product catalog and determines the various type of functions and operations that can be supported for each attribute. For example, a numeric dataType will allow operations such as less than and greater than and range facets; whereas a text dataType will support operations such as contains and support text facets.

Schema Format

The schema is part of a larger JSON feed file and is defined by the “schema” node. Each JSON object within the schema represents a field within your catalog.

Each field must contain the following four properties:

fieldName (Mandatory)
dataType (Mandatory)
multiValued (Mandatory)
autoSuggest (Mandatory)
isVariant (Optional)
id (Optional)

NOTE: While we recommend you upload both the schema and catalog as a unified JSON file, you can also upload the schema as a separate file.

fieldName

The fieldName specifies the name of the attribute such as title, color, and brand. Field names are case-sensitive; should start with an alphabet or underscore; can only contain alphanumeric characters, hyphens and underscores; cannot contain special characters, spaces, or end with an underscore.

id

The id in schema specifies a numerical identifier for an attribute in the catalog. Useful when product feeds may have the fieldID instead of the fieldName.

dataType

A dataType defines the type of value a specific field can have. We support the following dataTypes.

dataType	Format	Description	Searchable
text	String	Used for text fields such as title, color, brand, style etc.	yes
longText	String	Used for large text fields such as description and summary. Not every catalog will contain fields required to be marked as longText.	yes
decimal	Decimal	Used for fields that take decimal values such as price, discount, etc.	–
number	Numeric	Used for fields that take numeric values such as, quantity, orderCount, viewCount, etc.	–
link	URL (string)	Used for fields that take URL strings as values such as, productUrl, imageUrl, etc.	–
date	ISO 8601 date format (YYYY-MM-DDTHH:MM:SSZ)	Used for fields that take date values such as, createdAt, updatedAt, etc.	–
bool	true/false	Used for fields that take boolean values such as, availability, hasBanner etc.	–
sku	String	Used for fields that uniquely identify a product such as sku, product number, part number etc.	yes
path	String	Used for fields that are hierarchical in nature. Eg, categoryPath. Different values within a hierarchy are separated using “>”. Eg, “Men>Shoes>Casual Shoes”	–
facet	String	Internal reserved schema type used by Unbxd when processing for spelling, stemming, or tokenization is not required; not to be used by customers unless directed by Unbxd.	–
nsku	String	This data type is mainly used for B2B catalogs and supports any substring match, including prefix match, suffix match along with special character handling, as well as camel case and alpha-numeric searches.	yes

NOTE: Data Types of fields that are made searchable display those products on the search results page. Data Types that are not searchable can be used for filtering, sorting, and faceting.

multiValued

A multiValued attribute determines if a field can have multiple values for a product. For example, a Nike shoe can be considered sporty and casual in which case you could send multiple values for a style field: “style”:[“casual”,”sport”]. However, a field such as brand would be single-valued: “brand”:”Nike”. To enable a field to accept multiple values, set multiValued to true, otherwise to false.

isVariant

Only required for catalogs with variants, if an attribute is a variant field instead of a parent product field, set it to true, else set it to false.

Sample Schema

{
"feed": {
        "catalog": {
            "schema": [{
                "fieldName": "code",
                "dataType": "text",
                "multiValued": "false",
                "autoSuggest": "false",
                "isVariant": "false"
            }, {
                "fieldName": "title",
                "dataType": "text",
                "multiValued": "false",
                "autoSuggest": "false",
                "isVariant": "false"
            }, {
                "fieldName": "imageUrl",
                "dataType": "link",
                "multiValued": "true",
                "autoSuggest": "false",
                "isVariant": "false"
            }, {
                "fieldName": "brand",
                "dataType": "link",
                "multiValued": "true",
                "autoSuggest": "false",
                "isVariant": "false"
            }, {
                "fieldName": "brand",
                "dataType": "link",
                "multiValued": "true",
                "autoSuggest": "false",
                "isVariant": "false"
            }, { 
                "fieldName": "vPrice",
                "dataType": "decimal",
                "multiValued": "true",
                "autoSuggest": "false",
                "isVariant": "true"
            }]
        }
 }
}

Schema Upload Process

You can upload a schema using APIs with the exception of instances where any post-processing is performed by Unbxd on your schema which requires an SFTP upload.

Every schema upload appends to an existing schema, if any. You can update the characteristics

In case the schema has fields that are already found within an existing schema, the property values of the existing fields are updated. Similarly, when the new schema has new fields that are not found within an existing schema, the existing schema appends and adds the new fields. It is currently not possible to delete existing fields through the schema API.

API Parameters

The API parameters along with sample request and response are defined below:

API End Point

Parameters

siteKey: A unique identifier provided when your Unbxd account is created. This key can also be retrieved from your Unbxd Console. This is a required field.

secretKey: A unique identifier provided when your Unbxd account is created. The secretKey is used to authorize your upload request. This is a private key and will not be exposed to the public. This is a required field.

file: The name of the schema, as a JSON file.

feed end point : The feed end point depends upon the region selected at the time of site creation.

US region: http://feed.unbxd.io/

ANZ region : http://feed-anz.unbxd.io/

UK region : http://feed-uk.unbxd.io/

SG region : http://feed-apac.unbxd.io/

Error Codes

Sample Request

curl -X POST https://{Feed end point}/api/{siteKey}/upload/schema 
-H 'Authorization:{secretKey}' 
-F file={file}

Best Practices

To ensure your schema is uploaded and integrated seamlessly, here are some practices we recommend:

Schema is required for all fields (except for internal fields created by Unbxd)
Schemas not adequately defined will be rejected.
Ensure your schema 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.

Prepare Catalog

In this section, we define the product catalog and its attributes and different ways of sending your catalog to the Unbxd system. The catalog file contains a list of all your products and its attributes. The information associated with products is managed by search engines using attributes or fields.

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.

Fields

The product attributes store information related to a particular product. The attributes in a catalog can be classified into following categories :

UniqueId
Feature Fields
Custom Fields

UniqueId

UniqueId is a unique identifier that is associated with every product in the catalog and it is used to uniquely identify a product. Also known as a Stock Keeping Unit (SKU) or a productID (pid), the unique identifier helps the search engine keep a track of sales of a particular product and maintain your store’s inventory. The UniqueId attributes may not be visible to the shoppers and can remain completely hidden.

NOTE: Specifying 'UniqueId' for a product is mandatory.

Feature fields

Feature fields are a list of Unbxd fields that are necessary for majority of basic functionality to work and are expected to be included in your catalog.

fieldname	multiValued	dataType	Description
uniqueId (mandatory field)	false	text	Unique identifier of a product. It cannot have special character except ‘-’ and ‘_’
variantId	false	text	Unique identifier of a variant (if present). It cannot have special character except ‘-’ and ‘_’. It needs to be unique across entire product catalog.
variants	true	text	Field holding all the variants for a product.
title	false	text	Title or name of a product.
price	false	decimal(or double)	Price of a product.
description	false	longText	Description of a product.
category	true	text	Name of the category a product belongs to.
subCategory	true	text	Name of the sub-category a product belongs to.
categoryPath (mandatory field)	true	path	The category hierarchy of a product separated by “>” such as “Men>Shoes>Casual Shoes” Note: If categoryPathId below is included, categoryPath is not required as it will be generated automatically by the system.
categoryPathId	true	text	For catalogs that have category ids available, categoryPathId represents the mapping between category names and category ids. IDs and Names need to be separated using “\|”. For example: “cat100\|Home>cat101\|Luggage & Travel Accessories>cat102\|Travel Accessories”
imageUrl	true	link	URL of a product image.
productUrl	false	link	URL of the Product Detail Page (PDP) of a product.
currency	false	text	Currency of a product.
brand	true	text	Brand of a product.
color	true	text	Color of a product.
availability	false	bool	The availability of a product in “true”/“false” format.
sku	false	sku	Unique identifier for an item.
gender	false	text	Gender for a product.
size	true	text	Size of a product.
rating	false	decimal	Rating for a product.
discount	false	decimal	Discount on a product.
sellingPrice	false	decimal	Selling price of a product.

NOTE: If your catalog contains a feature field with a different name, you can either map it to the corresponding feature field from the Unbxd Console or rename your existing field to a feature field in the schema.

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.

Searchable fields

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.

The list of searchable attributes can be modified from the Console. The settings to modify searchable fields is available under Manage > Configure Search > Relevancy Ranking. The changes made in searchable fields from the console are only available after the next successful feed indexing. In the “Relevancy Ranking” section, only those attributes are available whose dataType qualifies for searchable criteria.

Variants

Variants are products that share the same SKU or productID (PID) but have at least one or more fields, like color, size, patterns 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 add variants to your existing feed. In each of the illustrations below, variants are configured to appear differently.

Illustration 1 : The HDMI cable has 5 variants – color, size, gauge, quantity, and output.

Illustration 2: In the illustration below, the product ‘Mango Badam’ has 1 variant – size. The PLP chooses to display the product as two separate entities here.

Illustration 3: In this illustration, the skirt has two variants – color and size. The other fields like title, description, fabric/material, price are the same.

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.

Upload Feed

We support three methods of feed upload:

Rest APIs: Use our custom REST APIs to upload your feed directly
Secure File Transfer Protocol: Upload your feed through an SFTP. Feed files uploaded on SFTP servers are transformed and uploaded to Unbxd servers. SFTP upload supports feed files in CSV, JSON and XML formats.
Platform Extensions: Our platform extensions can be used to upload feed seamlessly. Integrate our Magento 2 , Shopify or SAP Hybris plugin to automate catalog transfer from these platforms.

Did this answer your question?
Yes!
Nice work, I love it.
Feedback is submitted

Feed Creation

Prepare Schema

Schema Format

Sample Schema

Schema Upload Process

API Parameters

Best Practices

Prepare Catalog

Fields

Feature fields

Custom fields

Searchable fields

Variants

Best Practices

Upload Feed

Yes!

On this Section