Overview
When working with our JSON API, it’s important to structure your HTTP requests correctly to ensure successful execution. Here’s a brief overview to guide you:
To authenticate your requests, certain headers must be included. Please refer to the Authentication Documentation for detailed instructions on the required headers and authentication process.
The request body should be a JSON object tailored to the specific API operation you intend to execute. Refer to the URL and HTTP method type (GET, PUT PATCH, etc.) as specified in the Swagger/OpenAPI Specification
A successful request will return an HTTP 200 status code. For information on other possible status codes and their corresponding response messages, consult the Swagger/OpenAPI Specification
All APIs generally have a request size limit of 2MB. In case of For additional validations or specific limits for certain APIs, refer to the Swagger/OpenAPI Specification
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 ItemType from Swagger/OpenAPI Specification
- 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 Swagger/OpenAPI Specification.
- “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 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 Customer Groups to understand how to use this in detail.
