XML API

the klevu indexing api is organized around rest http //en wikipedia org/wiki/representational state transfer our api has predictable resource oriented urls, accepts xml request bodies, returns xml encoded responses, and uses standard http response codes, authentication, and verbs every record (e g a product, category, cms page etc ) sent to klevu is maintained in a dedicated index for the respective store the indexing api is used for adding, updating or deleting records from this index the indexing api requires that you first authenticate yourself to the klevu servers as a result of this authentication, you are provided with a session id which you can use for subsequent requests to the klevu servers api key & endpoint you must have a klevu search account to use the klevu api please access the shop info section of your klevu merchant centre to retrieve the following credentials rest api key (private key) for submitting data to be indexed, eg abcdefoobar== product synchronization url for submitting data to be indexed, eg rest klevu com what is a record? with klevu a record can be a product , a category page or a cms page that you want to index and make available in search results it can also be a custom record type such as a store or recipe or something like that when you submit a record for addition or update, you must submit the record with all of its details provided a list of mandatory and optional fields is provided below when you submit a record for deletion, however, you only need to submit its unique id attributes id string string | | required this is the unique identifier of a record klevu will use this id for indexing, analytics and merchandising itemgroupid string string | | optional if your data contains a shirt in 2 different colours and 3 different sizes, you must submit 6 product variants to indicate which group each variant belongs to, specify a common value in this itemgroupid element name string string | | required this is the name or title of your record sku string string | | required this is the unique sku of the record, or stock keeping unit url string string | | required this is the url where shoppers will be taken to when the record is clicked in the klevu search results this must be a fully qualified url, beginning http // or https // note that you may receive a 400 bad request if you submit a base url that has not been configured in your klevu merchant centre currency string string | | required the currency code of the prices specified below, e g eur, usd, gbp price double double | | required the original price of your product, before any discounts this can be used as was price when used in conjunction with saleprice in the case of a non product record, 0 0 must be provided as the value permitted characters in this field are 0 to 9 (digits) and (dot) for adding a decimal point for example, 12999 00 is a valid value, however $12999 or 12,999 00 are not please specify the currency information in the separate currency element saleprice double double | | required this is the final price of your product, after all applicable discounts this can be used as 'now price' when used in conjunction with price the format of this field is the same as price startprice double double | | optional if your record has multiple variants, this field can be used to show the lowest price across all variants, for displaying "as low as £100" toprice double double | optional if your record has multiple variants, this field can be used to show the highest price across all variants, for use in conjunction with startprice to display "from £100 to £200" groupprices string string | optional this field is mostly commonly used in magento integrations for the customer group prices to be rendered on the frontend the format of this field is 1\ general 100 00 there are three colon separated values in each price grouping the first value represents the id of the group, the second is the label, and the third is the price for that group please see the xml to the right for a full example otherprices string string | optional this is an improvement over groupprices , in that the values specified here can also be used in conjunction with pricefieldsuffix to retrieve dynamic prices based on currencies and customer groups the format of this field is price usd group 1 100 00 there are two colon separated values in each price grouping the first value represents the id of the group and the second is the price for that group the id is made up of the following format price type currency code group id , with the group id being optional if you are not using currencies please see the xml to the right for a full example of the possible variations instock string string | optional this attribute indicates if your record is in stock or not provide a value of yes if in stock, and no otherwise in case if you are not submitting stock status, klevu will consider product as out of stock please configure klevu stock setting https //help klevu com/support/solutions/articles/5000871482 hide out of stock products to show out of stock products category string string | required this attribute indicates the most specific category of the record being submitted for example, if your product belongs to the following categories mobiles & accessories tablets promotions new in it is only tablets and new in that should be specified here, separated by a semicolon ;, for example tablets;new in listcategory string string | required this field contains up to three pieces of data, depending on your use case each section of the field must be separated by a double semicolon ;; record type the first part is always required, a record type you must provide one of the following values, whichever is most appropriate for your record klevu product for product records klevu category for category records klevu cms for cms pages or blog articles your type for your own custom entity, eg acme recipe category hierarchy the second part is made up of the entire hierarchies of applicable categories the record belongs to, with each category within the hierarchy separated by a single semicolon ; using the same example as in category above, the following would be submitted for this section mobiles & accessories;tablets;;promotions;new in group id the third part is optional, and only needed if you plan to use the visibilitygroupid feature in api requests to control which customer groups can see which records this is made up of a double semicolon ;; separated list of all applicable customer groups for this record, eg customer group 1;;wholesale group see the xml to the right for a full example image string string | optional this is the url of an associated image for your record this must be a fully qualified url, beginning http // or https // imagehover string string | optional this field can be used to specify an additional image for your record to be used on mouse hover the format is the same as for image shortdesc string string | optional the short description for your record this field can be used to display a smaller description of a record in the search results desc string string | optional the long description for your record this can also be configured to be considered in search results, in which case both this value and shortdesc will become searchable other string string | optional use this field to specify filterable attributes for your product, to be used as facets the value is made up of three values separated by colon , then each attribute is separated by a semicolon ; attribute code caption or label value(s) for example occassion\ occassion\ christmas,evening wear the attribute code here is a unique identifier of your attribute the attribute caption is used as the heading of your filter when displaying search results if the attribute code, caption or values contain a comma, colon or semi colon, they must be replaced with a space otherattributetoindex string string | optional the format of this element is the same as the format of the other element above the difference between the two is that other is used for displaying facets whereas otherattributetoindex is used for indexing and searching only populate this field with any attributes you want to be searchable, but not used as a facet boostingattribute string string | optional the score provided here is multiplied with the relevancy score to boost records at search time any decimal value between the range of 0 1 to 999 can be provided here provide a value greater than 1 to boost a record up the rankings to de boost or demote a record, provide a number that is greater than 0 and less than 1 rating string string | optional a score between 0 and 5 this can be used for displaying a star rating with each record, and can also be used to apply a sort order of the highest rated items rating count string string | optional use this field to specify the number of ratings given by customers for your product tags string string | optional use this field to specify any important keywords applicable for your records swatches string string | optional if your record has many variants, you can specify swatch data to be used across them you must specify the same swatch data for all variants, and the format is made up of four elements, which is repeated with a suffix of 1, 2, 3, etc for each variant variantid1 the klevu id of the variant, eg 123 abc variantcolor1 the colour of the variant base css color name or hex value variantswatchimage1 (optional) the url of the image to be displayed as the swatch itself variantimage1 the product image that this swatch represents see the xml below full example additionaldatatoreturn string string | optional if you have some data that you would like to be returned with the search response, populate that data in this field the structure can be anything you like, but we recommend json if you do not see this in your response data, please contact klevu support by submittng a support ticket requesting a session id use this call to authenticate yourself to the klevu indexing servers in the response, you will be provided with a session id which you should use for all subsequent requests to the klevu servers you will need your rest api key and product synchronization url please refer to the prerequisites https //docs klevu com/apis/data indexing#muovk section for more information adding new records you must provide each record in full, including all mandatory parameters for every record you submit prerequisites you will also need a session id , please see the section above on requesting a session id updating existing records you must provide each record in full, including all mandatory parameters for every record you submit prerequisites you will also need a session id , please see the section above on requesting a session id deleting existing records you must provide the unique ids of the records you wish to delete prerequisites you will also need a session id , please see the section above on requesting a session id