XML API

7 min

The Klevu Indexing API is organized around REST. 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.

id string | required

This is the unique identifier of a record. Klevu will use this ID for indexing, analytics and merchandising.

itemGroupId 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 | required

This is the name or title of your record.

sku string | required

This is the unique SKU of the record, or Stock Keeping Unit.

url 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 | required

The currency code of the prices specified below, e.g. EUR, USD, GBP.

price 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 | 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 | 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 | 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 | 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 | 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 | 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 to show out of stock products.

category 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | optional

Use this field to specify the number of ratings given by customers for your product.

tags string | optional

Use this field to specify any important keywords applicable for your records.

swatches 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 | 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 section for more information.

Session ID

The end point is used for obtaining session id.

POST

https://<productSynchronizationURL>/rest/service/startSession

curl --location --request POST 'http://rest2.ksearchnet.com/rest/service/startSession' \
--header 'Authorization:  abcdefoobar=='

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.

Add New Records

The end-point is used for adding new records to index.

POST

https://<productSynchronizationURL>/rest/service/addRecords

curl --location --request POST 'https://<productSynchronizationURL>/rest/service/addRecords' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <sessionId>Your-Session-ID</sessionId>
    <records>
        <record>
            <pairs>
                <!-- IDs -->
                <pair>
                    <key>id</key>
                    <value>123-ABC</value>
                </pair>
                <pair>
                    <key>itemGroupId</key>
                    <value>123</value>
                </pair>

                <!-- Product Information -->
                <pair>
                    <key>sku</key>
                    <value>SKU-123-ABC</value>
                </pair>
                <pair>
                    <key>name</key>
                    <value>My Product Name</value>
                </pair>
                <pair>
                    <key>inStock</key>
                    <value>yes</value>
                </pair>
                <pair>
                    <key>url</key>
                    <value>https://your-website.com/products/123.html</value>
                </pair>
                <pair>
                    <key>image</key>
                    <value>https://your-website.com/images/products/123-abc.jpg</value>
                </pair>
                <pair>
                    <key>imageHover</key>
                    <value>https://your-website.com/images/products/hover/123-abc.jpg</value>
                </pair>

                <!-- Product Descriptions -->
                <pair>
                    <key>shortDesc</key>
                    <value>My Short Description</value>
                </pair>
                <pair>
                    <key>desc</key>
                    <value>My Longer Description</value>
                </pair>

                <!-- Prices -->
                <pair>
                    <key>currency</key>
                    <value>GBP</value>
                </pair>
                <pair>
                    <key>price</key>
                    <value>150.00</value>
                </pair>
                <pair>
                    <key>salePrice</key>
                    <value>100.00</value>
                </pair>
                <pair>
                    <key>startPrice</key>
                    <value>50.00</value>
                </pair>
                <pair>
                    <key>toPrice</key>
                    <value>200.00</value>
                </pair>
                <pair>
                    <key>otherPrices</key>
                    <value>price_GBP:150.00;price_USD:200.00;salePrice_GBP:100.00;salePrice_USD:150.00;startPrice_GBP:50.00;startPrice_USD:100.00;toPrice_GBP:200.00;toPrice_USD:300.00;price_GBP-test_group_1:100.00;price_USD-test_group_1:150.00;salePrice_GBP-test_group_1:80.00;salePrice_USD-test_group_1:100.00;startPrice_GBP-test_group_1:30.00;startPrice_USD-test_group_1:50.00;toPrice_GBP-test_group_1:180.00;toPrice_USD-test_group_1:200.00;price_GBP-test_group_2:90.00;price_USD-test_group_2:140.00;salePrice_GBP-test_group_2:70.00;salePrice_USD-test_group_2:90.00;startPrice_GBP-test_group_2:20.00;startPrice_USD-test_group_2:40.00;toPrice_GBP-test_group_2:170.00;toPrice_USD-test_group_2:190.00</value>
                </pair>
                <pair>
                    <key>groupPrices</key>
                    <value>test_group_1:Test Group 1:80.00;test_group_2:Test Group 2:70.00</value>
                </pair>

                <!-- Categorisation -->
                <pair>
                    <key>category</key>
                    <value>Sub Category A-2;Sub Category B-2</value>
                </pair>
                <pair>
                    <key>listCategory</key>
                    <value>KLEVU_PRODUCT;;Category A;Sub Category A-1;Sub Category A-2;;Category B;Sub Category B-1;Sub Category B-2;;test_group_1;;test_group_2</value>
                </pair>

                <!-- Attributes -->
                <pair>
                    <key>other</key>
                    <value>color:Colour:red;occasion:Occasion:Christmas,Evening Wear</value>
                </pair>
                <pair>
                    <key>otherAttributeToIndex</key>
                    <value>brand:Brand Name:Nike,Adidas;gtin:GTIN:123456789</value>
                </pair>
                <pair>
                    <key>rating</key>
                    <value>3.5</value>
                </pair>
                <pair>
                    <key>rating_count</key>
                    <value>10</value>
                </pair>
                <pair>
                    <key>tags</key>
                    <value>keyword 1,keyword 2</value>
                </pair>

                <!-- Swatches -->
                <pair>
                    <key>variantId1</key>
                    <value>123-ABC</value>
                </pair>
                <pair>
                    <key>variantColor1</key>
                    <value>Red</value>
                </pair>
                <pair>
                    <key>variantSwatchImage1</key>
                    <value>https://your-website.com/images/swatches/red.jpg</value>
                </pair>
                <pair>
                    <key>variantImage1</key>
                    <value>https://your-website.com/images/products/456-abc.jpg</value>
                </pair>

                <pair>
                    <key>variantId2</key>
                    <value>123-BCD</value>
                </pair>
                <pair>
                    <key>variantColor2</key>
                    <value>White</value>
                </pair>
                <pair>
                    <key>variantSwatchImage2</key>
                    <value>https://your-website.com/images/swatches/white.jpg</value>
                </pair>
                <pair>
                    <key>variantImage2</key>
                    <value>https://your-website.com/images/products/123-def.jpg</value>
                </pair>

                <!-- Miscellaneous -->
                <pair>
                    <key>boostingAttribute</key>
                    <value>5</value>
                </pair>
                <pair>
                    <key>additionalDataToReturn</key>
                    <value>{"some_arbitrary": "data to return"}</value>
                </pair>
            </pairs>
        </record>
    </records>
</request>'

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.

Update Existing Records

The end-point is used for updating existing records to index.

POST

https://<productSynchronizationURL>/rest/service/updateRecords

curl --location --request POST 'https://<productSynchronizationURL>/rest/service/updateRecords' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <sessionId>Your-Session-ID</sessionId>
    <records>
        <record>
            <pairs>
                <!-- IDs -->
                <pair>
                    <key>id</key>
                    <value>123-ABC</value>
                </pair>
                <pair>
                    <key>itemGroupId</key>
                    <value>123</value>
                </pair>

                <!-- Product Information -->
                <pair>
                    <key>sku</key>
                    <value>SKU-123-ABC</value>
                </pair>
                <pair>
                    <key>name</key>
                    <value>My Product Name</value>
                </pair>
                <pair>
                    <key>inStock</key>
                    <value>yes</value>
                </pair>
                <pair>
                    <key>url</key>
                    <value>https://your-website.com/products/123.html</value>
                </pair>
                <pair>
                    <key>image</key>
                    <value>https://your-website.com/images/products/123-abc.jpg</value>
                </pair>
                <pair>
                    <key>imageHover</key>
                    <value>https://your-website.com/images/products/hover/123-abc.jpg</value>
                </pair>

                <!-- Product Descriptions -->
                <pair>
                    <key>shortDesc</key>
                    <value>My Short Description</value>
                </pair>
                <pair>
                    <key>desc</key>
                    <value>My Longer Description</value>
                </pair>

                <!-- Prices -->
                <pair>
                    <key>currency</key>
                    <value>GBP</value>
                </pair>
                <pair>
                    <key>price</key>
                    <value>150.00</value>
                </pair>
                <pair>
                    <key>salePrice</key>
                    <value>100.00</value>
                </pair>
                <pair>
                    <key>startPrice</key>
                    <value>50.00</value>
                </pair>
                <pair>
                    <key>toPrice</key>
                    <value>200.00</value>
                </pair>
                <pair>
                    <key>otherPrices</key>
                    <value>price_GBP:150.00;price_USD:200.00;salePrice_GBP:100.00;salePrice_USD:150.00;startPrice_GBP:50.00;startPrice_USD:100.00;toPrice_GBP:200.00;toPrice_USD:300.00;price_GBP-test_group_1:100.00;price_USD-test_group_1:150.00;salePrice_GBP-test_group_1:80.00;salePrice_USD-test_group_1:100.00;startPrice_GBP-test_group_1:30.00;startPrice_USD-test_group_1:50.00;toPrice_GBP-test_group_1:180.00;toPrice_USD-test_group_1:200.00;price_GBP-test_group_2:90.00;price_USD-test_group_2:140.00;salePrice_GBP-test_group_2:70.00;salePrice_USD-test_group_2:90.00;startPrice_GBP-test_group_2:20.00;startPrice_USD-test_group_2:40.00;toPrice_GBP-test_group_2:170.00;toPrice_USD-test_group_2:190.00</value>
                </pair>
                <pair>
                    <key>groupPrices</key>
                    <value>test_group_1:Test Group 1:80.00;test_group_2:Test Group 2:70.00</value>
                </pair>

                <!-- Categorisation -->
                <pair>
                    <key>category</key>
                    <value>Sub Category A-2;Sub Category B-2</value>
                </pair>
                <pair>
                    <key>listCategory</key>
                    <value>KLEVU_PRODUCT;;Category A;Sub Category A-1;Sub Category A-2;;Category B;Sub Category B-1;Sub Category B-2;;test_group_1;;test_group_2</value>
                </pair>

                <!-- Attributes -->
                <pair>
                    <key>other</key>
                    <value>color:Colour:red;occasion:Occasion:Christmas,Evening Wear</value>
                </pair>
                <pair>
                    <key>otherAttributeToIndex</key>
                    <value>brand:Brand Name:Nike,Adidas;gtin:GTIN:123456789</value>
                </pair>
                <pair>
                    <key>rating</key>
                    <value>3.5</value>
                </pair>
                <pair>
                    <key>rating_count</key>
                    <value>10</value>
                </pair>
                <pair>
                    <key>tags</key>
                    <value>keyword 1,keyword 2</value>
                </pair>

                <!-- Swatches -->
                <pair>
                    <key>variantId1</key>
                    <value>123-ABC</value>
                </pair>
                <pair>
                    <key>variantColor1</key>
                    <value>Blue</value>
                </pair>
                <pair>
                    <key>variantSwatchImage1</key>
                    <value>https://your-website.com/images/swatches/blue.jpg</value>
                </pair>
                <pair>
                    <key>variantImage1</key>
                    <value>https://your-website.com/images/products/123-abc.jpg</value>
                </pair>

                <pair>
                    <key>variantId2</key>
                    <value>123-BCD</value>
                </pair>
                <pair>
                    <key>variantColor2</key>
                    <value>White</value>
                </pair>
                <pair>
                    <key>variantSwatchImage2</key>
                    <value>https://your-website.com/images/swatches/white.jpg</value>
                </pair>
                <pair>
                    <key>variantImage2</key>
                    <value>https://your-website.com/images/products/123-def.jpg</value>
                </pair>

                <!-- Miscellaneous -->
                <pair>
                    <key>boostingAttribute</key>
                    <value>5</value>
                </pair>
                <pair>
                    <key>additionalDataToReturn</key>
                    <value>{"some_arbitrary": "data to return"}</value>
                </pair>
            </pairs>
        </record>
    </records>
</request>'

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.

Delete Existing Records

The end-point is used for adding new records to index.

POST

https://<productSynchronizationURL>/rest/service/deleteRecords

curl --location --request POST 'https://<productSynchronizationURL>/rest/service/deleteRecords' \
--header 'Content-Type: application/xml' \
--data-raw '<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <sessionId>Your-Session-ID</sessionId>
    <records>
        <record>
            <pairs>
                <!-- IDs -->
                <pair>
                    <key>id</key>
                    <value>123-ABC</value>
                </pair>
            </pairs>
        </record>
    </records>
</request>'