Skip to content

Product data

The product feed is mandatory and must include all products that Hello Retail will manage. Variants should be clearly defined, and any shared data should be inherited from master products as appropriate.

The feed can be ingested using Hello Retail's Product Feed tool. You can find the documentation for it here.

Product Feed Principles

  1. Include all products required for recommendations or search.
  2. Provide correct URLs as they appear on the website. The URLs are used as the ID in Hello Retail.
  3. Include metadata as it is displayed on the site (not just as it is stored in the database).

If the master product serves only as a container for its variants and lacks its own information, it should inherit the details from the default variant.

Conversely, if the variants do not have specific information, they should inherit shared data from the master product.

Product Data

Hello Retail's system is highly flexible, allowing you to include any custom data.

Required fields

Each product in the feed must contain the following fields:

  • url: Canonical url of the product. This functions as the ID
  • ean: EAN Number of the product
  • price: Current price of the product
  • title: Title of the product
  • description: Description of the product
  • imgUrl: URL for an image of the product
  • inStock: Boolean indicating if the product is in stock or not

Optional fields

Each product in the feed can contain the following optional fields:

  • created: The date where the product was considered new.
  • priceExVat: Current price without VAT.
  • oldPrice: If the product is on sale, this will contain the previous price of the product.
  • oldPriceExVat: If the product is on sale, this will contain the previous price of the product without VAT.
  • productNumber: A product number identifying the product. Should be unique across the product catalog
  • variantProductNumbers: If a product is one of multiple variants of the same thing. This field can contain a list of the product numbers of all variants of that product
  • keywords: Keywords for the product, typicall used when searching
  • brand: Brand of the product
  • hierarchies: A hierarchical structrue describing the categories the product is in. On most shops a product is in multiple categories, this is a list of lists.
  • extraData.*: Extra string attributes for the product.
  • extraDataNumber.*: Extra number attributes for the product.
  • extraDataList.*: Extra string list attributes for the product.

Read more about extraData in feeds here.

Notes about product data

Product data should ideally reflect how it is presented on the site, rather than how it is stored in your shop database.

Example: If a shirt is categorized in the shop system as "Female," "Denim," and "New Arrivals," but on the site it is navigated through "For Women" > "Practical Outfit" > "Shirts," the second version (as displayed on the site) should be included in the feed.

Example

Below you can find an example of a product feed

[
    {

        "url": "https://www.domain.com/cool-bike-helmet",
        "ean": "1234576251872",
        "price": 100,
        "title": "Cool Bike helmet",
        "description": "This bike helmet has a great fit with an adjustable strap. comes in two colors.",
        "imgUrl": "https://www.domain.com/cache/250x250/cool-bike-helmet.jpg",
        "inStock": true,
        "created": "2024-12-24 12:01:02",
        "priceExVat": 80,
        "oldPrice": 200,
        "oldPriceExVat": 160, 
        "productNumber": "1234576251872",
        "variantProductNumbers": ["1234576251872", "1234576251873"],
        "keywords": "safety man woman biking",
        "brand": "Albus",
        "hierarchies": [
            ["Helmets", "Men"],
            ["Helmets", "Women"],
            ["Campaigns", "Winter Sale"]
        ],
        "extraData": {
            "strapColor": "Blue",
            "packaging": "plastic"
        },
        "extraDataNumber": {
            "strapLength": 25,
            "weight": 560
        },
        "extraDataList": {
            "sizes": ["S", "M", "L", "XL"],
        }
    },
    {...}
]