March 2021: This is our new XML Feed Format, also known as Feed V2. All new feeds should be created using this format. Those who created a feed using our old format can find reference materials here: Legacy Feed Format.
There are three steps involved in providing a feed of your store data to Klevu:
- Review the XML Sample and XSD Schema.
- Populate an XML feed file with your store's data.
- Share your feed so Klevu can regularly download it.
That’s all there is to it. The rest of this page covers these three steps in more detail.
1. Review the XML Sample and XSD Schema
The best way to get started is to download our XML Sample file, which contains a valid implementation of the Klevu feed format, complete with inline comments on what to do with each element of the feed.
The XSD Schema contains the various rules and validation aspects of the Klevu Feed format. Please reference this XSD directly so your XML Editor or IDE can assist you with inline validation of your data, for example:
2. Populate your store data
The next step is to populate your own XML feed with data from your store. Klevu requires your full catalog of all products that you would like to be included in your search results.
3. Share your Klevu Feed
Finally, host your XML file in a publicly accessible location and share the URL with Klevu Support (email@example.com), who will configure our monitoring service to download your feed at regular intervals. For example, your feed URL might look like this.
Frequently Asked Questions
If you need more help then please refer to the Frequently Asked Questions below, where you will find the most up-to-date information. Alternatively, feel free to reach out to Klevu Support (firstname.lastname@example.org) who will be happy to assist you.
Are there any more examples of feeds I can follow?
You can find some additional examples
in our GitHub repository, which focus on specific scenarios to give you an idea of how to provide various data to Klevu. This FAQ section covers our most common queries, so you may also find what you need here.
Why have you chosen this format?
You might wonder why we have structured certain elements the way we have, for example, our price elements contain a value together with a currency code:
We have actually followed the same principles of a Google Product Feed (as it stood early 2020)
as we found that many of our customers already have one. However, certain aspects required by Klevu are not found in the Google specification, so we have also introduced our own elements such as <additional_currencies/> and <groups/>. The result is a feed format that should work well with something our customers already have, but with the flexibility to provide all of the data required by a fully featured Klevu integration.
I already have a Google XML feed, can I use it?
If you already have a Google XML Feed you have a head start, but it is still important to read through this section carefully to ensure your feed is fit for Klevu. Whilst your feed may look good enough at a glance, you may be missing out on some valuable functionality.Google Feed: Product IDs
The Google definition for ID recommends you use SKU for this field. With Klevu it is also acceptable to use SKU as your ID, and provide the same value for <sku>, however, you must ensure that all SKUs in your store will conform to our ID specification (ie. alphanumeric with underscores only). Due to this schema requirement in Klevu IDs, we recommend using your database’s unique numerical identifier for the record. For example in Magento, Shopify and BigCommerce this would be the numeric Product Variant ID rather than the SKU, eg. v12345678.Google Feed: Missing Products
Some Google XML feeds only contain a subset of your product catalog since Google only needs to know about the products you want to merchandise with them. Klevu requires your full catalog of all products you want to be made available for search and category navigation.Google Feed: Missing Elements
There is a chance that your Google XML feed already contains enough information to get started with Klevu, however there is also a chance that if you do not review the Klevu schema you will miss out some important data. For example our schema includes some elements which are not found in a Google feed, such as specifying additional custom attributes, multiple currencies and even non-product entities like Categories and CMS pages. We recommend using your Google XML feed as a starting point, but to still check through the remainder of the documentation to make sure you’re getting the most out of Klevu.
I already have a feed in CSV / JSON / other format, can I use it?
We only support the XML data type, as defined in the Klevu XSD Schema
.What about Google CSV Feeds?
We do not support feeds in the Google CSV format. Maintaining a CSV file would be very complicated, given the nested nature of some elements such as groups and custom attributes, which are defined within our XSD Schema.What about JSON / TSV / CSV / Excel / etc.?
We do not support CSV, JSON or any other format than XML. Our feed format has been carefully designed to ensure we can retrieve all of the data needed from your store, so you can utilise everything Klevu has to offer.
I already have a Klevu Feed, should I upgrade to V2?
The short answer here is you don't need to upgrade to Feed V2. If you already have a feed which is working well, giving you all of the functionality you require in a format you can maintain, then there is no requirement
The main benefit of Feed V2 is the cleaner data structure, which will make it easier to integrate any new functionality Klevu may come out with in the future. So the next time some modifications are required to your feed, for any reason, that's the time to consider whether using Feed V2 would make it easier to complete that change.
Should I include parent and child/variant items?
If your store has compound products or configurable products, made up of a parent and one or more children or variants, it is only the variant items that you should include in your feed. For those items, whether you include the data like name, description, SKU, etc. from the parent or the variant is up to you, as it depends on what you would like to appear in your search results.
In order to group your variants together under their common parent, please use the <item_group_id/> element, where you can specify the ID of the parent or some common identifier amongst your variants. You can find more examples of this in the XML Sample.
Do I need to specify Swatch data for all variants?
Our legacy feed format had a requirement that information about all variants of a particular compound product be provided, for every variant. This meant you had to duplicate a lot of information for each variant.
With Feed V2 we have simplified this. For each <item/> you need only provide the <swatch_label/> and <swatch_color/> for that particular item. Klevu will then take care of ensuring the swatch data is shared across all sibling variants.
Can I add more than just Products?
If you want to make other content such as CMS Pages, Recipes, Shop Locations, etc. available to search, you can include them in your feed. This is detailed within the XSD Schema and Sample XML file and involves specifying the type of record in the <item_type/> element.
You can provide a single feed file containing all of your Product, Category, CMS and custom entities together, or you can split them into multiple feed files if you prefer. Please see the section in the FAQ on splitting large feeds.
How does Klevu detect changes?
Once the XML feed is uploaded it needs to be kept up to date by your team. Whenever an item changes in your source system, such as its price or stock status, this XML file must be updated to reflect the current status of that item. How and when you perform this task is up to you.
Each time we download your feed file, we compare it to the last version we downloaded. During this process we are able to identify any new items, any items which have changed, and also items which have been deleted, by comparing items which existed in the previous feed but are no longer present in the new feed.
How are deletes handled?
Due to the way we detect changes above, removal of an item can be triggered by simply omitting that item from a future feed. For example if Monday’s feed contains Product A, that product will be indexed by Klevu and made available in the search results. If on Tuesday the feed does not contain Product A, it will be deleted from Klevu and will no longer appear in search results.
How often does Klevu download the feed?
By default Klevu will download your feed every 12 hours. If this is not suitable, together with Klevu support (email@example.com
) you can agree on the most appropriate scheduling to ensure Klevu is downloading your feed after it has been updated by your internal systems, including specifying the regularity and best times of the day in your timezone.
Can I split a large feed into smaller parts?
If you have a particularly large catalog, or many different entity types to maintain, it is possible to split the feed across multiple files so you don’t need to maintain one huge XML file.However, it is important that the same file will always contain the same items. If this is not the case and you have random items appearing across the various feed files, you may find items being deleted when they should not be. This is because Klevu handles deletes by comparing the items found in the current feed with the last one we downloaded.
One method of achieving this split is by the item ID or type, for example:
- Feed A always contains items with ID 0 - 100,000
- Feed B always contains items with ID 100,001 - 200,000
- Feed C always contains only CMS items
- Feed D always contains only Category items
- and so on…
Does Klevu support delta / incremental feeds?
If you have some items that change more regularly than others or you want to keep on top of changing prices and stock status on a smaller scale, you can also provide us one or more supplemental feeds containing incremental changes only. Please find more information about this here: Delta / Incremental Feeds
Can I secure my feed?
If it is important that you keep your feed URL and its contents private, there are options available such as HTTP Authentication, IP Restriction or SFTP Upload. Please contact Klevu Support (firstname.lastname@example.org
) if you would like to explore this further.
Do you support multiple currencies?
Yes it is possible to add multiple currency values of your items. Please refer to the <additional_currencies/> element which can be found in the XSD Schema
My store has multiple languages, should they be added to the same feed?
Ideally not, no. There are various Natural Language Processing algorithms that Klevu applies for different languages, so it is best to submit any language variations of your data in separate feeds, which will be added to separate Klevu indexes.
I read all of this and still need help...
No problem, please feel free to email Klevu Support (email@example.com
) who will be happy to assist you.
What would be the format of CMS feed?
What would be the format of Category feed?