General info on feeds:
As a general principle, the Hello Retail solution can only be as good as the supplied data allows. Therefore, you must 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.
Data formats
JSONL / JSON Lines
JSONL stands for "JSON Lines" or "JSONLines". It is a format for storing structured data that consists of a sequence of JSON objects, one per line. Each line in the file is a valid JSON object, but there is no wrapping JSON array like in a regular JSON file.
JSONL is often used for storing or transmitting large amounts of data too big to fit into a single JSON document. Instead of storing all of the data in a single file, JSONL allows data to be stored as a stream of separate JSON objects, which can be read and processed one at a time.
JSONL files are often used in applications that generate or consume large amounts of data, such as log files, machine learning datasets, or data pipelines. The format is simple and easy to parse, making it a popular choice for data exchange between systems.
This is now our most preferred format for consuming external data. By leveraging the compact data for high-volume data exchanges and HTTP response headers we can support similar features as JSON and XML format in a more performant way.
A partial example of a potential JSONL product feed:
{"title":"Product 1","url":"https://example.com/products/1","price":99.95}
{"title":"Product 2","url":"https://example.com/products/2","price":199}
{"title":"Product 3","url":"https://example.com/products/3","price":399}
{"title":"Product 4","url":"https://example.com/products/4","price":410}
Hello Retail supports marking extraData, extraDataList and extraDataNumber fields as filterable. This makes it possible to use these fields for filtering in Search and Pages, and makes them available for personalization as well. Enabling fields for filtering can be done on My Hello Retail. Alternatively it is possible to provide the list of fields that should be filterable directly in the JSONL feed. This is done by adding a metadata object. This object needs to appear before any actual content in the feed. The meta data object looks like this:
{"helloRetailMetaDataType":"FIELD_METADATA","metadata":{"filterableFields":["extraData.size", "extraData.rate","extraDataNumber.width","extraDataList.colorsInStock"]}}
{"title":"Product 1","url":"https://example.com/products/1","price":99.95}
{"title":"Product 2","url":"https://example.com/products/2","price":199}
{"title":"Product 3","url":"https://example.com/products/3","price":399}
{"title":"Product 4","url":"https://example.com/products/4","price":410}
Where the presense of the property helloRetailMetaDataType makes the object a metadata object. The value of the type indicates that it is providing field metadata. The actual metadata is an object where currently only the list of field names that should be filterable is supported.
Note that the list of filterable fields is updated immediately as this element is parsed. Content that is parsed after this element is seen will have these new settings applied. The settings are global, so if multiple feeds are configured for products of for the same content type it is important to understand that the filterableFields configured in one feed affects the others. This means that in general these settings should only appear in one feed, and that it makes sense to only include the information on the first page of a paginated feed.
JSON
JSON is a lightweight and flexible data interchange format that is widely used for transmitting data between applications. It uses a text-based format that is easy for humans to read and write, and for machines to parse and generate. JSON has become a popular alternative to other data interchange formats, such as XML, due to its simplicity and flexibility.
A partial example of a potential JSON product feed:
{
"products": [
{"title":"Product 1","url":"https://example.com/products/1","price":99.95}
{"title":"Product 2","url":"https://example.com/products/2","price":199}
{"title":"Product 3","url":"https://example.com/products/3","price":399}
{"title":"Product 4","url":"https://example.com/products/4","price":410}
],
"latePageNumber":47,
"extensionVersion":"1.1.26",
"deltaToken":"1682681545"
}
Hello Retail supports marking extraData, extraDataList and extraDataNumber fields as filterable. This makes it possible to use these fields for filtering in Search and Pages, and makes them available for personalization as well. Enabling fields for filtering can be done on My Hello Retail. Alternatively it is possible to provide the list of fields that should be filterable directly in the JSON feed. This is done by adding a metadata object. The metadata will only be found if it is available in a helloRetailMetaData property directly at the root object of the feed. It will look something like this:
{
"helloRetailMetaData": {
"filterableFields":["extraData.size", "extraData.rate","extraDataNumber.width","extraDataList.colorsInStock"]
},
"products": [
{"title":"Product 1","url":"https://example.com/products/1","price":99.95}
{"title":"Product 2","url":"https://example.com/products/2","price":199}
{"title":"Product 3","url":"https://example.com/products/3","price":399}
{"title":"Product 4","url":"https://example.com/products/4","price":410}
]
}
XML
In the past, our feed system primarily ingested XML feeds. However, the industry has trended towards JSON for quite some time, and this has caused a shift in how APIs and systems consume data. While we still support XML to a certain extent, all data downloaded from our system is converted to JSON format. This conversion process may result in some data inconsistencies, such as uncertainties in data type or the application of artifacts during the conversion process.
Therefore, we generally consider the XML format for sending data to our system as deprecated. We strongly advise all new feed development for shop platform plugins to utilize JSONL or JSON format for sending data.
A partial example of a potential XML product feed:
<?xml version="1.0"?>
<response>
<item>
<products>
<item>
<product>
<title>Product 1</title>
<url>https://example.com/products/1</url>
<price>20</price>
</product>
</item>
<item>
<product>
<title>Product 2</title>
<url>https://example.com/products/2</url>
<price>99</price>
</product>
</item>
<item>
<product>
<title>Product 3</title>
<url>https://example.com/products/3</url>
<price>125</price>
</product>
</item>
<item>
<product>
<title>Product 4</title>
<url>https://example.com/products/4</url>
<price>99</price>
</product>
</item>
</products>
<last_page_number>47</last_page_number>
<extension_version>1.1.26</extension_version>
<deltaToken>1682681587</deltaToken>
</item>
</response>
You can read more about XML on the official website https://www.w3.org/XML.