Avg. 10 min read Setup and Data Synchronization Requirements¶
This guide is part of the general setup for unsupported platforms. Find the main page for the full general guide here.
General info on feeds:¶
Hello Retail relies on the quality of the data you provide. Supply product information in a consistent, structured format so it can be processed as-is.
Hello Retail uses feeds to synchronize data between your shop and our systems. Supported formats are JSON, XML, or CSV.
The data in these feeds must always match what is visible on the site.
For JSON, the root should look like this:
{
"extensionVersion": "1.0.0",
"deltaToken": "1605001940",
"totalCount": 1234,
"lastPage": 123,
"items": []
}
- extensionVersion: the version of the installed shop extension.
- deltaToken: a token used to request only changes since this feed was generated (include only if you implement delta feeds).
- totalCount: the total number of active products.
- lastPage: the last page number for the given pageSize (see Pagination below).
- items: the list of items on the requested page.
Delta feeds:¶
If a previous feed response included a deltaToken, the next request from Hello Retail will include that same deltaToken as a query parameter. Your platform must then generate a feed that only contains products changed since the feed that produced that token. This is not a new feed URL; the token is a parameter on your existing feed endpoint that filters the response to only changed products.
Delta feeds enable frequent synchronization by returning only changes. For example, instead of requesting a full feed hourly, we can request deltas every 10 minutes.
For even faster synchronization, you can use the Hello Retail API to trigger a delta feed run whenever products change. Many platforms expose events or webhooks for this. Read more here.
To implement delta functionality:
- Accept a deltaToken request parameter. When present, return only products changed since that token.
- Generate and return a new deltaToken for each feed response. The token can be any string. A timestamp is often practical, as it lets you query the platform for products changed since that time.
Security:¶
Authenticate feed requests by validating a key parameter against the random key generated by the extension (see the Extension UI requirement).
Hello Retail will include this key in all feed requests, for example:
Only expose feeds over HTTPS.
Pagination:¶
To reduce load, the extension must support pagination. When Hello Retail includes page and pageSize parameters, the extension should only return that slice of data. For example:
The response should contain only the first 100 products (page 0 is the first page).
If the pagination parameters are not present, return the full feed.
Shop variables:¶
If the platform supports multiple languages and/or currencies, the feed must return the requested translations and prices. For example:
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, the main product is the master product and the specific variations are variants.
General principles
The product feed should contain all products that Hello Retail must handle.
- Example 1: If your shop has 2000 products and you want meaningful recommendations, all 2000 must be in the feed.
- Example 2: If your shop has 2000 products and 500 have variations (size, color, etc.), and those variants should be searchable or recommended, include all master products and all variants.
- Example 3: If all 2000 products have variants but you only want Hello Retail to show and recommend the master products, include only the master products in the feed.
If the master product is an empty container, it should inherit data from its default variant.
If variants do not specify certain fields, they should inherit those fields from the master product.
Notes about the product URL¶
Product URLs in the feed must exactly match what is used on the site. If redirects, canonical tags, or rewrite rules change the displayed URL, expose the final on-site URL.
- Example: If a product URL in the shop system is http://www.example.com/men/shirts/blaa--skjorte.html but the visible or canonical URL is http://www.example.com/bla-skjorte.html, the feed must provide the latter.
Notes about metadata¶
Product metadata should match what is used on the site, not necessarily how it is stored in the database.
- Example: If a shirt is assigned to “Female”, “Denim”, and “New arrivals” in the backend, but on-site navigation is “For Women” > “Practical outfit” > “Shirts”, the feed should reflect the on-site structure.
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 are useful for Hello Retail Search or product recommendations.
The productData fields are explained in detail at the bottom of this guide, where there is also a sample product with data.
Some fields may not apply to your platform. Some may apply only to the master product or only to variants. Contact Hello Retail support before omitting fields or changing the structure.
- See an example here: Sample product
Order feed:¶
The order feed is essential for a good integration and is required.
By default, return orders from the last 2–3 days at the time of request. Also accept a daysBack parameter to request further back in time.
For example: http://domain.com/helloretail/orderfeed?daysBack=90 to fetch approximately three months of orders.
Below is the list of fields that should be present on each order entry in the feed:
orderData:
orderProductData:
If a variant was purchased, orderProductData must reference the variant.
- See an example here: Sample order
When exporting products as an XML file for product feed - CDATA:¶
When manually exporting products to XML for upload to product feeds, certain special characters must be handled correctly. The ampersand (&) and the less-than sign (<) are common sources of parsing errors. The parser may interpret “<” as the start of an element and “&” as the start of an entity.
Using CDATA (unparsed character data) avoids this by encapsulating text so the parser treats it as character data. An entity reference looks like:
A CDATA section is started with:
and ended with:
All data inside a CDATA section is interpreted as character data, not XML markup, and the parser ignores tags within it.
Content feeds:
Content feeds enable Hello Retail Search to find and return relevant site content. Applicable content types vary by platform. If in doubt, contact the Hello Retail development team.
Category feed:¶
The category feed is essential for customers using search and is therefore required. The feed should include all active categories for the site.
Below is the list of fields that should be present on each category entry in the feed:
categoryData:
- See an example here: Sample category
Blogpost feed:¶
Blogpost feeds are not required but are recommended when the platform supports blog content and it is relevant to the site.
The structure should be the same as for category feeds.
Brand feed:¶
If brand pages are distinguishable from category pages, provide a separate brand feed. If brands are not distinguishable, they can be included in the category feed and a dedicated brand feed is not needed.
The structure should be the same as for category feeds.
Sitepage feed:¶
Sitepage feeds are not required but are recommended when the platform supports such pages and they are relevant.
The structure 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:¶
Guides¶
Main page¶
Please contact Support if you have questions about this guide, or reach out to your account manager.