Product data feeds

Introduction

This document is meant to serve as a guideline for what data a product feed should contain for it to seamlessly integrate with the ebbot platform as well as enable utilization of all features that the product data system offers.

The following product feeds formats are accepted. Which one you choose to export your feed in is up to you.

  • JSON (with an array of all products)

  • NDJSON/JSONL (new line-delimited JSON, one product per line)

  • XML (preferably an RSS och Atom stream)

  • CSV (separated by any common separators, including TSV)

Data import types

Data can be imported in several ways depending on your preference and data source.

  • Upload a file

  • Data feed URL

  • Import file through ftp-server

  • Shopify integration

Feed data

The fields in a product feed customized for ebbot can be divided into two parts:

  • Common fields (fields with special meaning such as id, name, link, or price)

  • Other attributes (any other fields serving as attributes for creating product guides, such as color, size or flavor)

Common fields

Make sure that your feed contains at least the required fields. The field names can be changed during the import to ebbot.

Attributes

Any other fields present in your product feed can be imported and used as attributes when building product guides. It’s usually preferable to include as much data as possible - as this will make building easier and most likely lead to better product guides. In some cases, not enough data may lead to building any decent product guide being simply impossible.

Ebbot has a powerful feed importing tool that lets you rename fields, split values, extract attributes from product descriptions and much more. Yet, some tasks may be simpler to perform on your side than on ours. Therefore, here are some tips you can have in mind when exporting your product feed.

FORMAT NUMBERS ACCORDING TO THE FOLLOWING

There are two basic rules to follow:

  • Use dot (.) as the decimal separator

  • Don’t include spaces or any other separators as part of the number itself

Examples of correctly formatted numbers:

  • 199

  • 1999.99

  • SEK 199

  • 2000mm

  • weight: 14.2 kg

Examples of incorrectly formatted numbers:

  • 1 999

  • 199,99

  • 1,999.99

DON’T MIX VALUE FORMATS/UNITS

Mixing value formats or units will make it difficult to select the correct attribute values when building your guide, especially when there are a lot of values:

If possible, try separating such fields based on product category, value format or unit:

This will also simplify guide building as number attributes (such as shoe size) will be detected as such and become filterable by range.

SEPARATE FIELDS AND VALUES

Instead of providing a massive attribute field such as:

Try separating all attributes and their values into their own fields, such as:

Full and partial feeds

Ebbot support what we call full and partial feeds. A general use case for these is:

  • Full product feeds contain the full data set (all product attributes) but are updated less frequently

  • Partial product feeds contain only a subset of attributes (such as price and availability) and are updated more frequently

By default, the first product feed you upload becomes a full feed. Usage of partial feeds is not required but may be required by the service providing of your feed for frequent updates.

The previous section describes the required fields for a full feed. A partial feed however, only requires the id field (which must match the id in the full feed), along with the fields you want to update more frequently.

An example of a simple partial feed updating the availability and pricing of all products. Note that the attribute names and values must match with the full feed, eg. if you want to update the availability attribute using a partial feed, both the full and partial feeds need to have the same availability field in terms of name and values.

Localization

Ebbot supports, alongside building product guides in multiple languages, localized product feeds. This allows your guide to display product information such as name, price (in the correct currency) or any attribute, in the product guide’s language - all without you having to rebuild your guides for each language. In order for this to work correctly however, the localized feeds need to be correctly structured.

When creating a product collection, the first product feed you import becomes the “primary” language feed. This is the feed your guides are going to be based upon, e.g. product filtering/searching will occur on this feed. Other “secondary” language feeds connected to the same product collection are used solely for displaying localized information for your customer.

If you decide to use a localized product feed, you need to think about the following:

  • Our locale system assumes that secondary feeds only contain products that are present in the primary feed. Products in secondary feeds that are not present in the primary feed will never be displayed.

  • Secondary feeds should ideally be exact copies of their primary feed, only with translated field values. This is not a requirement as secondary only needs to contain the fields you want to display for your customers and that differ between locales. This usually includes price and description but may also include other attributes such as category, flavor or size if you want to display these attributes.

  • The secondary feed’s id fields must match the primary feed’s id field.

For example, given the following primary product feed in English:

A localized product feed in Swedish may look like the following:

Note that the id field in the secondary feed matches the id field in the primary feed and that both feeds have the same field names but with translated values (name, description, price, category and color). Technically, the size field could be omitted from the secondary feed since the sizes are identical in both locales. The category field could also be omitted from the secondary feed if you know that you never want to display this field localized for your customers.

Ebbot's feed import tool

Ebbot features a powerful feed import tool allowing you to rename field names and transform their values in many different ways, along with creating entirely new fields out of other fields. We recommend you familiarize yourself with the tool in order to understand what it is capable of doing. A few common possible operations are:

  • Changing field names, for example from Product title to name.

  • Splitting text values, for example Clothes > Men > T-shirts split on the character > becomes Clothes, Men and T-shirts.

  • Replacing text values, such as replacing the values yes and no in the field in stock with In stock and Out of stock, making them customer displayable, or replacing commas with dots and removing spaces in the price field.

  • Extracting field values from other field values into completely new fields, such as creating a new field environment based on whether the product description contains the text indoor or outdoor, etc. A different example is creating a new field energy class by extracting which letters that come after Energy class: in the product description.

Last updated