JSON API 🆕
Catalog or Product Structure
1min
For full details of the Entities and all attributes, please refer to API definition. In Klevu, each item needs to be indexed, i.e. if you have a complex product, like a Shirt, available in different sizes and colors, then you should index the Parent product “Shirt” and all the variants available as a different item in Klevu. Following are some of the key properties of the Item to understand how to structure a product.
- “id” field: Each item should have the unique “id”. Each item being submitted in the request should have the ID defined in the whole catalog. Even for complex products, ensure that parent products and variants have unique IDs in the full catalog. E.g. I cannot have a parent product with id “1” and variants with id “1”, “2” and “3”. Here parent and variant have a conflict at id “1”. Same way, I cannot have a CMS page with id “1” if there exists an item with id “1”.
- The “type” field represents the type of item. For catalog items, “KLEVU_PRODUCT“ is used. For other types, please refer to the API schema.
- The “attributes” field represents all the attributes of the item. The basic attributes that you will include in the product are “name”, “URL”, and “price”. There are other standard attributes available that can be used and defined in the API definition.
- “name”: You might notice that text fields like name, and description have defined values as { "default": "Product 1" } Fields with text value have been defined in the above format using "default". It will help us to expand the definition for other use cases in the future. For the time being, all text values have to follow the pattern as you see in the example.
- “URL”: URL is critical for the item being indexed and that is used to redirect the end-user on your site to the relevant page. It should typically have a value of the PDP page for the product, a Category page for the category, etc. For different variants in the complex product, if your platform supports variant-specific URLs, then it is recommended to use the variant flavor of URL, else you can also give a common parent product URL for all the variants.
- “price“: Prices are mandatory for the products being indexed. This is a list of different prices and “type” defines the use of the price. “currency” needs to be defined for each price, even if the store is using a single currency, it needs to be defined for each price of the product. If you are indexing multi-currency prices, then ensure that you give value for each currency for each product.
- “salePrice” is the mandatory type to be defined for each currency for each product. This is the price after all applicable discounts and will be displayed in the rendered product.
- “defaultPrice” is the original price, if defined, can be used to show a strikethrough while rendering the products.
- The “relations” field represents the relation of the item with other items in your catalog. We can map a parent and child product in a Complex product or map products in categories using relations. You will see this in action in one of the How to do (with examples).
- The “channels” field is used to represent alternative values of the properties for different channels or groups. E.g. we use it for defining a different price for a customer group on my site. Refer to the example Adding prices and visibility settings for customer groups to understand how to use this in detail.
Updated 01 Nov 2023
Did this page help you?