Skip to content

General Information on Feeds

The quality of the Hello Retail solution depends on the quality of the provided data. To ensure optimal performance, it is essential to supply product information in a structured format that Hello Retail can process and utilize directly. Please review this guide to ensure that your data feeds adhere to the required structure.

Hello Retail uses feeds to synchronize data between the client’s shop and our database. Feeds should be in one of the following formats: JSON, JSONL, XML, or CSV. The data in these feeds must always match what is displayed on the website.

Our feed system is quite flexible, and can be thought of as an ETL (Extract, Transform, Load). You can find more about our Feed System here.

Feed Types

We have 4 types of feeds, Product, Order, Content & Category feeds.

  • Product: This is the primary feed that is used to digest your products into our system.
  • Order: The order feed is to improve the personalization experience, and is used in our Audience solution.
  • Category: This feed is used in search to be able to find the category pages
  • Content: This is similar to the category data and is used in the search solution to be able to search for other content types, like for instance blog posts or brand pages

Pagination

On some platforms it might be difficult to support having all products in a single feed. To resolve this the feed system supports reading data from paginated feeds. If pagination is enabled Hello Retail includes page and pageSize parameters in a request. In that case the feed should only return the requested segment of the data.

Example request for pagination:

https://domain.com/helloretail/productfeed?page=0&pageSize=100

Shop Variables

If the shop platform supports multiple languages and/or currencies, the feeds should accommodate requests for translations and prices. Example request:

https://domain.com/helloretail/productfeed?language=en&currency=eur

Multi-Currency

For shops with multiple currencies, you should use a seperate 'website' in Hello Retail for each currency or language.

JSON Format Example

The root structure for a JSON feed should look like this:

{
    "extensionVersion": "1.0.0",
    "deltaToken": "1605001940",
    "totalCount": 1234,
    "lastPage": 123,
    "items": []
}

Field Definitions

  • deltaToken: A token used to track changes in the product catalog (only for delta feeds).
  • totalCount: Total number of active products available.
  • lastPage: The last page of results for a given page size (see Pagination).
  • items: The list of products on the requested page.

Delta Feeds

Delta feeds allow efficient synchronization by providing only the products that have changed since the last feed request. This reduces the need for frequent full-feed updates.

Delta feeds are implemented by:

  1. Accepting a deltaToken parameter: When Hello Retail includes a deltaToken in its feed request, only return products that have changed since that token.
  2. Generate a new deltaToken: Each feed response should include a deltaToken that can be used to fetch products that change after this current feed was generated. If the shop platform supports finding products that has changed since a certain date, it is often practical to use a timestamp as the delta token. The feed will be given the timestamp of the previous run, and can use that to find products that have changed since then.

Delta feeds can also be triggered programmatically using the Hello Retail API. Many platforms support event hooks that can be used for this purpose. Refer to the Hello Retail API Documentation for details.

Notes on Product URLs

Products are identified by their urls, so it is important that the URL returned in the product feed matches the URL that is used on the site. The helloretail.js script will track how often each product is viewed or added to the cart, and this tracking is done based on the URL. Some shops have multiple URLs that point to the same product, this is OK if the shop is correctly configured to have a canonical URL that matches the one in the feed. A correct implementation of canonical URLs is also important from a SEO perspective since Google will penalize sites where multiple urls have the exact same content if they do not have a canonical URL that points to the same place.