ChannelEngine: product feeds

About this article

This article describes product feeds, what is required to use them, how to set them up, and more.

Table of contents

Introduction

Product feed format

Password-protected feeds and FTP feeds

Set up a feed

• Feed operations
• Add a feed
• Feed settings

Mapping feeds

• Mapping columns
• Custom fields

Leading and additional feeds

Required, recommended, and optional fields

Delete fields

Formatting and encoding

Generate parents or grandparents

Examples of feeds

Introduction

A product feed is a file that is available online (e.g.: on your FTP server or a public resource like Google Sheets) and can be used by ChannelEngine to import your product data.

Product feed format

Product feeds must be provided in XML or CSV format. A TXT format is also allowed, as long as the XML or CSV format is used. When using CSV, the following delimiters are allowed:

• Semicolon (;)
• Comma (,)
• Pipe (|)
• Tab ( )

Each product must have a unique Merchant product number, which makes the product unique in ChannelEngine's database. Commonly used attributes are the SKU, the EAN or a unique ID from the source system. Make sure to map the correct attribute for this identifier, as mistakes may lead to products not appearing on ChannelEngine.

Password-protected feeds and 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 using HTTP basic authentication, use the following format:

https://[Username]:[Password]@[YourHost]/[FileName].xml

E.g.: 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

Depending on the protocol used, adjust the above format to start with ftps, sftp, or ftp.

E.g.: ftps://testuser:1234@myshop.com/feed.xml

Take into account that special characters are automatically converted to their HTML-encoded counterparts when using a URL, which can cause issues with authentication. Therefore it is advised to not use special characters (e.g.: $ # % ^ * : @) in your password, to prevent any authentication errors.

FTP access with a key file

It is not possible to add a feed protected by 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 future, please refer to the ChannelEngine Ideas Board.

Set up a feed

Product feeds can be managed and added under the Product feed overview, which is accessible by selecting the product feed box in the dashboard – or by selecting Products > Product feeds in the left-hand side menu.

It is possible to use multiple product feeds, as long as there are no duplicate identifiers in leading feeds. I.e.: each Merchant product number should only be available in one leading product.

Feed operations

As well as adding a feed with the Add feed button, there are other operations that can be performed from the Product feed overview. There are also some feed-specific characteristics visible.

• Name - the name given to the feed.
• URL - the URL where the feed can be downloaded from.
• Type - the type of feed (CSV or XML), and if it is a leading or additional feed.
• Most recent import - the timestamp of the latest import of the feed by ChannelEngine.
• Next import - the timestamp of the next scheduled import of the feed.
• Status - the result of the current or last import of the feed.
• Validation report - redirects you to a separate page which shows the number of active, inactive, and new products from the last import. It also shows which products could not be imported and why, and lists warnings for products that have mapped attributes with invalid data.

• Edit - allows you to edit an existing product feed. This redirects you to the feed mapping.
• Delete - deletes an existing product feed. Bear in mind that this also marks all products in the feed as deleted, if the feed is a leading one.
• Start import - forces the import of a product feed manually. Make sure not use this too often in short succession, as data in product feeds does not have to be updated very frequently – and it increases the load on ChannelEngine's services.

Add a feed

Once you select the + Add feed button, you are asked to input the location of the feed.

Select the correct delimiter, if using a CSV feed (i.e.: what character separates individual columns in the CSV), or the product node in case of an XML feed (i.e.: what tag marks an individual product in the feed). Select Continue when the correct value is selected. The suggested correct value is highlighted in green, but this is based on how often a specific character is encountered, so make sure to verify it.

The product nodes available in the dropdown are based on the number of occurrences of elements, or subnodes, in the feed. The minimum is of two occurrences.

The following example results in two nodes: <product> and <price>. As it has only one subnode – and two is the minimum for a workable product attribute –, <info> is not included.

<xml>
   <price>
     <sku>1</sku> 
     <price_in_EUR>40</price_in_EUR>
   </price>
   <price>
     <sku>2</sku> 
     <price_in_EUR>40</price_in_EUR>
   </price>
   <price>
     <sku>3</sku> 
     <price_in_EUR>40</price_in_EUR>
   </price>
   <product>
     <sku>4</sku>
     <title>awesome</title>
     <description>something</description>
    <price>40</price>
   </product>
   <product>
     <sku>5</sku>
     <title>awesome</title>
     <description>something</description>
     <price>40</price>
   </product>
   <product>
     <sku>6</sku>
     <title>awesome</title>
     <description>something</description>
     <price>40</price>
   </product>
   <product>
     <sku>7</sku>
     <title>awesome</title>
     <description>something</description>
     <price>40</price>
   </product>
   <info>
     <sku>8</sku>
  </info>
   <info>
     <sku>9</sku>
   </info> 
</xml>

Feed settings

Once you select Continue after setting the correct delimiter or product node, the feed details page loads. At the top of this page, you see a section with product feed settings.

• Name - the name of the product feed. If you plan to use multiple feeds, make sure to distinguish them by using different names. E.g.: Stock feed supplier 1, Product feed refurbished items, Product translations feed - DE.
• Select the delimiter or product node - this is the delimiter or product node you selected for the feed. It is possible to change it in an existing feed, but there is a risk of undesired results. Make sure not to change this setting unless you know what you are doing.
• Additional - marks a feed as additional. Additional feeds are meant to update attributes of existing products (e.g.: stock, content, etc.)
• Use comma separator in numbers - by default, ChannelEngine's servers are set to the US/international locale. This means that for numbers (i.e.: prices, dimensions, etc.), ChannelEngine expects a period as the decimal separator (e.g.: EUR 9.95). If your feed uses a European locale and numbers with a comma as the decimal separator (e.g.: EUR 9,95), make sure to enable this setting to prevent prices from being 100 times higher.
• Generate parent products - if this setting is enabled, ChannelEngine automatically generates parent products if a parent SKU is mapped – and no parent product is available in the feed.
• Generate grandparent products - if this setting is enabled, ChannelEngine automatically generates grandparent products if a grandparent SKU is mapped – and no grandparent product is available in the feed.

Mapping feeds

Below the settings, you can see the feed mappings that need to be set to import products and its data in the correct fields in ChannelEngine. These feed attributes have to be mapped to ChannelEngine attributes.

Mapping columns

There are three columns for mapping:

1. Left column - lists the name of the attribute on ChannelEngine. At the top, you see ChannelEngine specific attributes such as the EAN, the Merchant product number, and the Stock. In the custom fields section, it shows the name you assigned to a custom attribute.
2. Center column - shows the mapped attribute from your feed. If the EAN of the product is located at the attribute EAN, for example, you need to map that. In the initial load of the feed, suggested attributes are highlighted in green and show a light bulb icon. This disappears once the mappings are saved.
3. Right column - shows the preview of a specific value for that attribute. The first ten items found in the feed are available for preview. This is a good way to check if the attribute you select has the correct values.

For each product feed you add, it is possible to map an attribute under the center column. However, if you use a separate feed for the stock, many attributes do not have to be mapped for that specific feed – only the Merchant product number and Stock attributes.

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

• Not mapped - Clear value - useful when the 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, it is advised to use Not mapped - Keep value as a value. Using Clear value removes product information during every import of that feed if there is something to be removed, and if it is mapped in a different feed it triggers an update with every feed import. This can cause undesired results. E.g.: if you have a product selection rule based on an attribute with a value and feed 1 sets it, but feed 2 clears it, the product is removed and added every x minutes from the 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 select the + Custom fields option, you see a list of available attributes that can be used for custom fields. Green attributes are already mapped to a ChannelEngine field or custom field. Orange attributes 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 have already been added, you can use the Custom fields management on ChannelEngine.

Leading and additional feeds

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

Leading feed

A leading product feed contains the core products, and is what is used to create or remove products on 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 gets the ID of that feed. If a product is no longer available in that specific feed, the product is marked for deletion.
• Can be used to create parent or grandparent products, but not simultaneously.

Additional feed

An additional feed contains 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 such as translations coming from a different system.

• Must contain the Merchant product number of the products you want to update.
• Cannot be used to create new products.
• Cannot be used to delete new products.
• Cannot be used to create parent or grandparent products.

Required, recommended, and optional fields

Required

The following attributes are needed to create a viable product on ChannelEngine. In theory, only a Merchant product number is enough, but managing products and channels like this is harder and more time-consuming.

Field	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 (incl. VAT)	49.95
Stock	Product stock	25
Merchant product number	Your unique product number	192354
EAN	Product GTIN (EAN, ISBN, UPC)	8710400311140
Image link	Deep link to the product's image	http://www.theshirtshop.com/images/products/192354.jpg
Category	The product's full category path (with each category separated by >)	Men's > t-shirts > crew neck

Recommended

While not mandatory, it is highly recommend to provide the following attributes in your feed.

Field	Description	Example
Catalog price	MSRP (incl. VAT)	59.95
Purchase price	Product purchase price (excl. 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

The following fields are not required, although in some situations they may be conditionally required (e.g.: MerchantGroupNo).

Field	Description	Example
Parent SKU	The Merchant product number of the parent product, it connects parent and child products	192350
Grandparent SKU	The Merchant product number of the grandparent product, it connects grandparent and parent 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	Deep link to the product's additional images	http://www.theshirtshop.com/ images/products/192354-1.jpg

* = Only for affiliate networks/click channels.

Other additional fields might be added to the feed. These fields can be used to filter products on ChannelEngine, or to be passed along to one of the mappable attributes.

Delete fields

Occasionally, you may need to delete a field from your product feed. When you delete a field, ChannelEngine removes the value from that field following the next feed import.

Formatting and encoding

If you want to include special characters or content in descriptions or other attribute values (e.g.: HTML in an XML file, or quotation marks in a CSV file), make sure to properly 'escape' them.

XML

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

<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 ( ). If your attribute value has meaningful spaces, the entire value should be enclosed in quotation marks. For an example of part of a CSV row containing attribute values that need to be escaped, see below:

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. If you do not specify the encoding for your product feed or if it is in an encoding format other than UTF-8, odd characters appear on product data. It is highly recommended to provided all data in UTF-8 formatting to prevent incorrect decoding.

Generate parents and grandparents

If a leading feed does not contain parent or grandparent products, these can be automatically created by ChannelEngine. It is required that the feed containing children already have a shared identifier grouping them, which could be used as the Merchant product number for the parent.

Parents and grandparents can be created the following options:

• Generate parent products
• Generate grandparent products

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, and EAN are set to null (empty)
• Values, including custom fields, are 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 is set to null (empty)

New grandparent

• Size and color are set to null (empty)

 

Examples of feeds

The following examples can help you understand the concepts and guidelines mentioned in this guide:

• XLSX product feed
• XML product feed