Setup and Data Synchronization Requirements
This guide is part of a general setup guide for unsupported platforms. Find the main page for the full general guide here.
General info on feeds:
As a general principle, the Hello Retail solution can only be as good as the supplied data allows. Therefore, it is important that you provide product information in a structured fashion that enables us to read and use it “as is”. Please read through the guide and make sure the data feeds follow the structure explained.
Hello Retail uses feeds to synchronize data between client's shop and our database. The feeds should be in either JSON, XML or CSV format.
The data in these feeds must always match what is seen on the site.
For JSON, this is what the root should look like:
{
"extensionVersion": "1.0.0",
"deltaToken": "1605001940", (only if you support delta feeds!)
"totalCount": 1234,
"lastPage": 123,
"items": []
}
- extensionVersion being the version of the extension currently installed on the shop.
- deltaToken being a token that can be used in the future to request changes to the product catalog since this current feed was generated.
- totalCount being the total count of active products available.
- lastPage being the last page with a given pageSize (see pagination below).
- items being the list of items on the request page.
Delta feeds:
If a previous feed has supplied a deltaToken, the next request from Hello Retail will include this deltaToken. The shop platform should then generate a product feed that only contains the products that have changed since the feed that generated that token. This isn't a new feed URL but a parameter for your regular feed URL that modifies it to only return the changed products.
The use-case for the delta feed is to provide an efficient way to synchronize your product catalog changes with higher frequency — so instead of requesting your full feed every hour, we can request only the changes and do it every 10 minutes instead.
For even faster synchronization, you can choose to utilize the Hello Retail API to trigger a delta feed request every time you make a change - many platforms have event hooks that can be used for this. You can read about that here.
To incorporate the delta functionality, you need to do the following:
- You need to accept a request parameter called deltaToken when Hello Retail requests your feed. When you receive a deltaToken as a query string parameter to your feed, you should only return products that have changed since that delta token.
- You need to create a new deltaToken when your feed is requested. This deltaToken can be any string. As mentioned above, it will be sent back to you on the next request and you can return any changed products. For many platforms, it would make sense to return a timestamp since this would allow you to query your shop platform for products that have changed since that point in time.
Security:
The extension should authenticate the requester of the feeds by checking that the request has a key parameter matching the random key generated by the extension (check the Extension UI requirement section).
The random key will be shared with Hello Retail and we will add it as a request parameter for all our feed requests like so:
domain.com/helloretail/productfeed?key=123xyz
We also recommend that feeds are only accessible via https.
Pagination:
To ease the load from the extension when requesting feeds, the extension needs to support pagination. When Hello Retail adds the parameters "page" and "pageSize" in a request then the extension should only generate a part of the complete feed.
So for a request like
domain.com/helloretail/productfeed?page=0&pageSize=100
the extension should generate a feed containing only the first 100 products.
If the pagination parameters are not present in the request then the feed should not be paginated.
Shop variables:
If the shop platform supports multiple languages and/or currencies, we should be able to request all the necessary translations and/or prices in the feeds.
A request could look like this:
domain.com/helloretail/productfeed?language=en¤cy=eur
Multi-currency:
Multi-currency can be supported by having one webshop per currency.
Feed types:
Product feed:
The product feed is essential and is, therefore, always required.
For products with variants, we will refer to the main product as the master product and the variations as variants.
General principles
The product feed should contain ALL of the products that Hello Retail should be able to handle.
- Example 1: If your shop contains 2000 products, and if Hello Retail is to be able to make meaningful product recommendations, then all of these 2000 products need to be present in the feed.
- Example 2: If your shop contains 2000 products, and 500 of these have variations (different size, colour etc.), and if Hello Retail is to make these either searchable or available as recommendations to other products, then all master products, as well as their variations, should be present in the feed.
- Example 3: If your shop has 2000 products and all of these have variations BUT you only want Hello Retail to show and recommend the master products, the feed should only contain these products and not their variations.
If the master product is simply an empty container for the variants, and therefore doesn't have information in itself, the master product should simply inherit the info of the default variant.
If variants don't hold specific info on their own, the shared data from the master product should be inherited by the variants.
Notes about the product URL
The URLs of the individual product should be EXACTLY the same as can be seen on the site – so if you have special redirect/replace-rules for how URLs behave in the browser, these should be considered when giving us the feed.
- Example: If a given product URL is defined as www.example.com/men/shirts/blaa--skjorte.html in the shop system but is “seen” as www.example.com/bla-skjorte.html (either in the browser, in open graph tags, in canonical tags or similar), then it is the second version of URL that should be made available to us in the feed.
Notes about metadata
Metadata about the product should ideally be the same as is used on the site, and not necessarily as it might be defined in your shop database.
- Example: A shirt has been assigned the following categories in the shop system: “Female”, “Denim”, and “New arrivals” – but on-site you navigate to the product through “For Women” > “Practical outfit” > “Shirts”, then it’s the second version that should be made available to us in the feed.
Below is the list of fields that should be present on each product entry in the feed:
productData:
type id sku ean productNumber price priceNoTax previousPrice previousPriceNoTax hasPriceRange currency title description hierarchies attributes keywords tags url imgUrl secondaryImgUrls overlay visibility inStock quantity createdDate isNews variants
You may add other fields that you find useful for our search engine or our product recommendations.
The productData fields are explained in detail at the bottom of this guide where there also is a sample product populated with data.
Some of the fields may not make sense with your shop platform and some may only make sense for the master product but not it's variants, or vice versa but please contact Hello Retail's support if you want to leave out a field or change the structure.
- See an example here: Sample product
Order feed:
The order feed is also essential to a good integration and is therefore also required.
It should contain orders from the last 2-3 days from the time the feed is requested as a default but accept a parameter named "daysBack" that allows going further back in time.
It could look like this domain.com/helloretail/orderfeed?daysBack=90 if you wanted to get orders dating approximately 3 months back.
Below is the list of fields that should be present on each order entry in the feed:
orderData:
id orderNumber orderProducts createdDate total email
orderProductData:
id url productNumber quantity price priceNoTax
If a variant product has been purchased then the orderProductData should be from that variant.
- See an example here: Sample order
When exporting products as an XML file for product feed - CDATA:
It is important to remember when manually exporting products as an .XML file for upload to product feeds that some special characters will not be parsed correctly. This means that it might get misinterpreted because of some specific syntax that needs extra review.
The two most common special characters is the "&" (ampersand) and the "<" (less-than sign, also known as the angle bracket). The “<“ will generate an error because the parser interprets it as the start of a new element. The "&" will generate an error because the parser interprets it as the start of a character entity.
Using CDATA, also known as (unparsed) character data, in this case will help to escape this issue by using encapsulation by creating a C section. This will create a entity reference instead such as:
&entityName;
A C section is created by starting it with
<![CDATA[
and ending it with
]]>.
All data within the C section will be interpreted as only character data and therefore not XML markup because the parser will ignore this C section.
Content feeds:
Content feeds are primarily used to enable our search engine to find and deliver relevant content on the customers' website. Some content types might be relevant for one shop system while others may be relevant for another - if you are in doubt then please contact the Hello Retail development department.
Category feed:
The category feed is essential for many customers using our search feature and is therefore also considered a requirement.
The feed should contain all the active categories belonging to the site.
Below is the list of fields that should be present on each category entry in the feed:
categoryData:
id url title hierachy keywords description
- See an example here: Sample category
Blogpost feed:
Blogpost feeds are generally not a requirement but are very nice to have anyway.
Whether it makes sense to include this depends on the shop platform - is it supported in the platform and is it an important part of its features?
The content of the feed should be the same as for category feeds.
Brand feed:
If brand pages are distinguishable from category pages in the shop platform then a specific brand feed is required. If however the brands can't be distinguished from the categories then the brand will naturally occur in the category feed and there is no need to create a specific brand feed.
The content of the feed should be the same as for category feeds.
Sitepage feed:
Sitepage feeds are generally not a requirement but it is very nice to have anyway. Whether it makes sense to include this depends on the shop platform - is it supported in the platform and is it an important part of its features?
The content of the feed should be the same as for category feeds.
productData fields specifications:
See a complete list here.
orderData, orderProductData and categoryData fields specifications:
See productData fields specifications above as the fields are the same.
Unsupported platforms:
Main page
Please feel free to contact Support if you have any questions to this guide or contact your designated account manager about this.