Product feeds

// Contents

Introduction
Product feed format
Password protected feeds / FTP feeds
Setting up a feed
   Feed operations
   Add a feed
   Feed settings
Mapping feeds
   Mapping columns
   Custom fields
Leading and additional feeds
Required and recommend fields
Formatting & encoding
Generate parents or grandparents
Example feed

// Introduction

A product feed is a file that is available on an online location that can be used by ChannelEngine to import all the product data (like individual attributes, stock and price levels). The requirements for a product feed are listed below. Please be aware that a product feed has to be available at an online resource (for example your FTP-server or a public resource like Google Spreadsheets) and can not be 'uploaded' to ChannelEngine manually.

// Product feed format

Feeds should be provided in XML or CSV-format (a TXT extension is also allowed as long as a proper XML or CSV format is used). When using CSV the following delimiters are allowed:

  • Semicolon ;
  • Comma ,
  • Pipe |
  • Tab \t

Each product must always have a unique MerchantProductNo which makes the product unique in our database. Commonly used attributes are the SKU, the EAN or a unique ID from the source system. Please make sure you map the correct attribute for this identifier, as making a mistake will lead to strange results like no products showing in ChannelEngine.

// Password protected feeds / FTP feeds

It is possible to import data from product feeds that are available via HTTP(S) or FTP(S) and are secured with a password.

/ HTTP(S)

To import a feed which is protected using HTTP basic auth, use the following format:  https://[Username]:[Password]@[Yourhost]/[Filename].xml
For example:  https://testuser:1234@myshop.com/feed.xml

/ (S)FTP(S)

To import a feed using FTP, use the following format: ftps://[Username]:[Password]@[Yourhost]/[Filename].xml

For example: ftps://testuser:1234@myshop.com/feed.xml

Please note: unencrypted FTP-connections are NOT supported, but both SFTP and FTPS (implicit and explicit) connections are. Unencrypted HTTP locations are allowed, but HTTPS has a strong preference.

Also take into account that special characters are automatically converted to their HTML encoded counterparts when using an URL, which can cause issues with authentication. Therefore it's advised to not use special characters such as $ # % ^ & * : @ in your password to prevent any authentication errors.

/ FTP access with a key file

At this time it's not possible to add feed protected via a .PPK key file to gain access to an FTP server. If this is an option you would like to see added to ChannelEngine in the future, please contact your customer success manager (they are in charge of feature requests) or send a mail to info@channelengine.com.

// Setting up a feed

The product feeds can be managed and added in the product feed overview, which is accessible by clicking on the product feed box on the dashboard, or by selecting 'Products > Product feeds' in the menu on the left. 

It is possible to import/use multiple product feeds, as long as there are no duplicate identifiers in leading feeds (so a MerchantProductNo should only be available in 1 leading product). 

/ Feed operations

Next to adding a feed (via the "+  Add feed" button), there are other operations that can be performed from the product feed overview. There are also some feed specific characteristics that are visible.

  • Name - this shows the name that's been given to this specific feed.
  • URL - the URL where the feed can be downloaded from.
  • Type - This shows what type of feed (CSV or XML) it concerns and if the feed is a 'leading' or 'additional' feed.
  • Most recent import - the timestamp of the latest import of this feed by the ChannelEngine system
  • Next import - the timestamp of the next scheduled import for the product feed.
  • Status - this will show the result of the current or last import of the product feed.
  • Validation report - by clicking on the button you will be directed to a separate page showing the amount of active, inactive, and new products from the last import(s). It will also show which products could not be imported and why, and will also list warnings for products that have mapped attributes with invalid data.
  • Edit - by clicking on the pencil icon, you can edit an existing product feed. This will redirect you to the feed mapping, which is explained in detail later in this guide.
  • Delete - by clicking on the trashcan icon, you can delete an existing product feed. Please be aware that this will also mark all products in that feed as deleted if the product feed is a leading one.
  • Start import - you can force the import of a product feed manually by pressing this option (the play button). Please do not use this too often in short succession, data in a product feed will usually not be updated that fast and it will increase the load on our services.

/ Adding a feed

  1. Once you pressed the "+  Add feed" option, you will first be prompted for the location of the feed.
  2. Next up you will need to select the correct delimiter if it concerns a CSV feed (so what character separates individual columns in the CSV), or the product node in case of an XML feed (what tag marks an individual product in the feed). Press continue when the correct value is selected (the suggested correct value will be highlighted in green, but is based on how often a specific character is encountered so please verify).

/ Feed settings

Once you pressed ' Continue' when selecting the correct delimiter or product node, the feed details page will load. On top of this page, you will see a section with settings for your product feed.

  • Name - the name for your product feed. If you are planning to use multiple feeds, it might be wise to enter a name to distinguish feeds. Examples: 'Stock feed supplier 1', 'Product feed Adidas items', 'Product translations feed - DE'.
  • Select the delimiter / Select the product <node> - this is the delimiter or product node you selected for your feed. It is possible to change it for an existing feed, but not without risk of undesired results. Please do not change this setting unless you are certain this will not cause issues.
  • Additional - this is to mark a feed as additional. Additional feeds are meant to update attributes (like the stock or enrich content) of existing products.
  • Use comma's in prices? - by default, our servers are set to the US / International locale. This means that for prices we expect a dot (so price = 9.95) as decimal separator. If your feed uses a European locale and prices use a comma (so price = 9,95), please make sure to enable this setting to prevent prices from being 100 times higher.
  • Generate parent products - this setting is to have ChannelEngine automatically generate parent products if a parent SKU is mapped and no actual parent product is available in the feed.
  • Generate grandparent products - this setting is to have ChannelEngine automatically generate grandparent products if a grandparent SKU is mapped and no actual grandparent product is available in the feed.

// Mapping feeds

Below the settings, you will see the actual ' feed mappings' which will need to be set in order to import the products and its data in the correct fields in ChannelEngine. These feed attributes have to be mapped to ChannelEngine attributes. 

/ Mapping columns

There are 3 columns for the mapping:

  1. LEFT COLUMN: this column will list the name of the attribute in ChannelEngine. On the top, you will see ChannelEngine specific attributes like the EAN, the Merchant product number and the stock. In the custom fields section, this will show the name you gave a custom attribute.
  2. CENTER COLUMN: this column will show the actually mapped attribute from your feed. So if the EAN for the product is located at the attribute 'ean', you will need to map that. In the initial load of the feed, 'suggested' attributes will be highlighted in green and show a lightbulb icon. This will disappear once the mappings are saved.
  3. RIGHT COLUMN: this column will show a preview of a specific value for that attribute. The first 10 items found in the feed are available for preview. This is a good way to check if the attribute you select has indeed the correct values.

For each product feed you add, it's possible to map an attribute in the center column. However, if you use a separate feed for the stock, many attributes will not have to be mapped for that specific feed (only the merchant product number and the stock attribute). 

There are 2 options for not mapping an attribute in a feed:

Not mapped - Clear value: useful when this field should be a fixed value. The fixed value can be mapped in channel mapping.
Not mapped - Keep value: useful when another product feed already fills this field. 

In most situations, we advise using  Not mapped - Keep value as a value. Using Clear value will remove product information during every import of that feed (if there is something to be removed), and if it is mapped in a different feed you will trigger an update with every feed import. This can cause undesired results: if you have a product selection rule based on an attribute having a value and feed 1 sets it, but feed 2 clears it, the product will be removed and added every x minutes from a channel.

/ Custom fields

Next to the ChannelEngine specific attributes you can map, there is also the option to add and map your own custom data attributes (or fields).

If you press the " +Custom fields" option, you will see a list of available attributes that can be used for custom fields. Orange colored attributes are attributes that are already mapped to a ChannelEngine or custom field. Green colored attributes are attributes that have not been mapped yet. It is possible to add an attribute as a custom field that is already used for another field.

To remove custom fields that already have been added, you can use the ' Custom fields management' in ChannelEngine.

// Leading and additional feeds

ChannelEngine allows for 2 types of product feeds: leading feeds and additional feeds.

/ Leading feed

A 'leading' product feed is a feed containing the core products and is what is used to create (or remove) products in ChannelEngine.

  • Must contain unique products (so the merchant product number should not be available via a different feed or another type of data import)
  • Using multiple leading feeds is possible as long as the merchant product numbers do not overlap.
  • When a product is created by one feed the product will get the id of that feed. If a product is no longer available in that specific feed, the product will be marked for deletion.
  • Can be used to create parent or grandparent products (but not simultaneous).

/ Additional feed

An 'additional' feed is a feed containing extra information to update existing products coming from a leading feed. This is useful if you have a separate stock feed you want imported more often or if you have product data like translations coming from a different system.

  • Must contain the merchant product number for the products you want to update.
  • Can not be used to create new products.
  • Can not be used to delete new products
  • Can not be used to create parent or grandparent products

// Required, recommended and optional fields

/ Required

The following attributes are needed to create a viable product in ChannelEngine. In theory, only a MerchantProductNo is enough, but you will have a very hard time managing products and channels:

Field Name Description Example
Name Product name Black T-Shirt with Crew Neck
Description Product description  A simple black T-Shirt from Fancy T-Shirts Inc…
Price Product price (Including VAT) 49.95
Stock Product stock 25
Merchant product number Your unique product number 192354
EAN Product GTIN (EAN, ISBN, UPC) 8710400311140
Image link Deeplink to the product’s image http://www.theshirtshop.com/images/products/192354.jpg
Category The product’s full category path (each category separated by  > ) Men’s > T-Shirts > Crew Neck

/ Recommended

While not mandatory, we strongly recommend supplying the following attributes in your feed(s):

Field Name Description Example
Catalog price MSRP (Including VAT) 59.95
Purchase price Product Purchase Price (Excluding VAT) 35.00
VAT % VAT Percentage 21.00
Brand Product Brand Name Fancy T-Shirts Inc.
Vendor product number Manufacturer / Supplier Product Number FTI-BLK-XL
Size Product Size XL
Color Product Color Black

/ Optional Fields

The following are not required, although in some situations conditionally required (like the MerchantGroupNo):

Field Name Description Example
Parent sku The Merchant product number of the parent product. This connects parent and child products. 192350
Grandparent sku The Merchant product number of the grandparent product. This connects grandparent and child products. 192
Details The product's details. A simple T-Shirt. Color: Black Brand: Fancy T-Shirts Inc
Url * Deep-link to the product’s details page http://www.theshirtshop.com/products/192354-black-t-shirt-with-crew-neck.html
Discount % The difference between the sale price and the MSRP in percentage 47.92
Margin % The margin between the price and purchase price in percentage 30
Shipping Cost Product shipping costs 5.95
Shipping time days Delivery time indication Ordered before 22:00: Shipped Today.
Extra image link x Deeplink to the product’s additional images http://www.theshirtshop.com/images/products/192354-1.jpg

* = Only for click-channels

Any other additional fields might be added to the feed, these fields can be used to filter products in ChannelEngine or to be passed along to one of the mappable attributes.

// Formatting & encoding

If you want to include special characters or contents (like HTML in XML or quotation marks in CSV) in descriptions or other attribute values, please be sure to properly "escape" them. 

/ XML

for XML you need to include the value between CDATA tags, like in below example

<description><![CDATA[This basic t-shirt has a <i>print</i> with a funny text. <br><br>The fabric is made of 92% cotton and 8% elastane.]]></description>

/ CSV

for CSV you need to use a quotation mark to escape special characters like the quotation mark itself ( " ), a comma ( , ) or a new line ( \n). Also if your attribute value has meaningful spaces (like at the end), the entire value should be enclosed in quotation marks. An example of a part of a CSV row containing attribute values that need to be escaped:

id, "This basic t-shirt has a ""print"" with a funny text. <br><br>The fabric is made of 92% cotton, 5% elastane and 3% awesomeness.", phone number, title,

/ Encoding

ChannelEngine uses UTF-8 as the default encoding for all data, so if you do not specify the encoding for your product feed or if it's in an encoding format we can not support, you'll see strange characters on product data. We strongly recommend supplying all data in UTF-8 formatting to prevent incorrect decoding.

// Generate parents or grandparents

If a leading feed does not contain actual parent or grandparent products, a (grand)parent can be automatically created by ChannelEngine. This does have the requirement that the feed containing the 'children' already have a shared identifier grouping them together that could be used as the merchant product number for the parent.

A (grand)parent can be created using either one of the two options:

  • Generate parent products
  • Generate grandparent products

Both options cannot be used at the same time (so the feed import logic can not create both a parent and a grandparent in the same import). This generation basically functions like this: if the Grandparent sku does not refer to an existing merchant product number (SKU), then a new product with the mapped Grandparent sku is created with that sku as its merchant product number. 

A generated product can be recognized by 'Parent (generated icon)' or 'Grandparent (generated icon)' in the product detail view.

/ What information is copied / set

For both generated parent and grandparent:
  • Stock, Grandparent sku, EAN will be set to null (empty)
  • Values (including custom fields) will be copied from the first parent/child below it.
  • The name of the new product is the longest common prefix (minus punctuation marks at the end).
New parent:
  • Size will be set to null (empty)
New grandparent:
  • Size and color will be set to null (empty)

// Example feed

Here you can find a simple example XML feed.