ChannelEngine: product feeds
About this document
This document describes product feeds, what is required to use them, how to set them up, and more.
Table of contents
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 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 (\t)
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.
It is possible to import data from product feeds that are available via HTTP(S) or FTP(S), and are secured with a password.
To import a feed which is protected using HTTP basic authentication, use the following format:
To import a feed using FTP, use the following format:
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, contact your Customer Success Manager or email ChannelEngine.
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.
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.
- 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.
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 to 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 commas in prices? - by default, ChannelEngine's servers are set to the US/international locale. This means that for prices ChannelEngine expects a period as the decimal separator (e.g.: EUR 9.95). If your feed uses a European locale and prices 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.
Below the settings, you can see the feed mappings which 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.
There are three columns for mapping:
- 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.
- 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 lightbulb icon. This disappears once the mappings are saved.
- 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.
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. Orange attributes are already mapped to a ChannelEngine field or custom field. Green 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.
ChannelEngine allows for two types of product feeds: leading feeds and additional feeds.
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.
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.
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.
|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|
|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|
While not mandatory, it is highly recommend to provide the following attributes in your feed.
|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|
The following fields are not required, although in some situations they may be conditionally required (e.g.: MerchantGroupNo).
|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 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||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.
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.
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>
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). 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,
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.
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 the 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
This generation works like this: if the Grandparent SKU does not refer to an existing Merchant product number (SKU), 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, 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
- Size is set to null (empty)
- 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: