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 sizes, 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

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 its variants, or vice versa but please contact Hello Retail's support if you want to leave out a field or change the structure.

Example: 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.

Example: 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 are 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 an 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
hierarchy
keywords
description

Example: 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.

orderData, orderProductData and categoryData fields specifications

The specifications are the same as productData fields defined above:

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