Prepare Your Catalog

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:

Method : POST

 

End Point :  {feed end point}/{siteKey}/upload/schema

 

Description : This API will perform an upload/update of the schema file.

Method : POST

 

End Point :  {feed end point}/{siteKey}/upload/schema

 

Description : This API will perform an upload/update of the schema file.

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/

Method : POST

 

End Point :  {feed end point}/{siteKey}/upload/schema

 

Description : This API will perform an upload/update of the schema file.

We use conventional HTTP response codes to indicate success or failure of an API request.

201 (Ok): Indicates the upload was successful.
401 (Authorization Error): Indicates you may have provided an invalid API key.
400 (Bad Request): Indicates you may have missed a required parameter.
500 (Internal Server Error): Though these are rare, this indicates we may have messed up.

Method : POST

 

End Point :  {feed end point}/{siteKey}/upload/schema

 

Description : This API will perform an upload/update of the schema file.

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:

Start by defining a schema for your custom fields. Unbxd Feature fields have a fixed predefined schema that cannot be modified.
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 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 preparing your catalog for upload. Once you’ve uploaded your catalog, it becomes the feed that powers our search solution on your eCommerce site. A catalog powers the content in an eCommerce site and contains attributes that describe properties of the product in more detail.

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. The attributes contain information about properties of the product.

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 predefined Unbxd fields with a fixed schema that doesn’t need to be defined in the feed file, and are automatically marked searchable.These fields are necessary for Autosuggest and Recommendations to work properly.

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. 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 be overwritten by the predefined default schema of that field.

Field Name	Multi Value	Data Type	Description
`uniqueId` (mandatory)	false	text	Unique identifier of a product. Cannot have special characters except ‘-’ and ‘_’.
`variantId`	false	text	Unique identifier of a variant (if present). Must be unique across entire catalog. No special characters except ‘-’ and ‘_’.
`variants`	true	text	Holds all the variants for a product.
`title`	false	text	Title or name of the product.
`price`	false	decimal (or double)	Price of the product.
`description`	false	longText	Description of the product.
`category`	true	text	Name of the category the product belongs to.
`subCategory`	true	text	Name of the sub-category the product belongs to.
`categoryPath` (mandatory)	true	path	Category hierarchy. Values separated using “>” (e.g., “Men>Shoes>Casual Shoes”).
`categoryPathId`	true	text	Category hierarchy with names and IDs. Format: `ID
`imageUrl`	false	link	URL of the product image.
`productUrl`	false	link	URL of the Product Detail Page (PDP).
`currency`	false	text	Currency of the product.
`brand`	false	text	Brand of the product.
`color`	true	text	Color(s) of the product.
`availability`	false	bool	Availability of the product (`true`/`false`).
`sku`	false	sku	Unique identifier for the item.
`gender`	false	text	Gender associated with the product.
`size`	true	text	Size(s) of the product.
`rating`	false	decimal	Product rating.
`discount`	false	decimal	Discount on the product.
`sellingPrice`	false	decimal	Selling price of the product.

📘
NOTE
Feature Fields can be used without explicitly defining them in the schema. If you have a similar field, you can either map it to the corresponding feature field from the 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.

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.