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

Leading and additional feeds

Create a feed

Set up a feed

• Feed operations
• Add a feed
• Feed settings

Mapping feeds

• Mapping columns
• ChannelEngine attributes
• Stock locations
• Custom attributes

Required, recommended, and optional attributes

Delete attributes

Formatting and encoding

Generate parents or grandparents

Examples of feeds

Validation report

Introduction

A product feed is a file that is available online, such as on a public resource like Google Sheets or an FTP server, and can be used by ChannelEngine to import your product data.

Product feed format

Product feeds must be provided in comma-separated values (CSV), extensible markup language (XML), or JavaScript object notation (JSON) format. The text (TXT) format is also allowed, as long as the XML or CSV structure is used. When using CSV, the following delimiters are supported:

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

Each product must have a Merchant product number, which makes the product unique in ChannelEngine's database. SKUs, GTINs, or any other unique IDs from your source system are the most commonly used. 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

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

FTP access with a key file

It is not possible to add a feed which relies on 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, refer to the ChannelEngine Ideas Board.

Leading and additional feeds

ChannelEngine allows for two types of product feeds: leading feeds and additional feeds. It is recommended that each feed has a maximum of 25 MB.

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.
• If your leading feed has more than 25 MB, move all the non-essential information within it to one or more additional feeds.

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.

Create a feed

Although you can create a product feed using spreadsheet software such as Google Sheets or Microsoft Excel, ChannelEngine offers a custom feed builder. To access it, go to the Channels page, search for 'feed channel', and click the Request to configure button.

Once your request is granted, open and configure the feed channel:

1. On the Setup page, choose the file format for you product feed: CSV, XML, or JSON. 
2. Under General settings, you can change the default name and image. This is particularly useful when using multiple feed channels.
3. Go to the Product selection page. You can either copy an existing selection or create one.
4. Proceed to the Feed settings page and click Add attributes. The only requirement is the name of the attribute. Note that this name must match exactly the name of the attribute on the marketplace where the product feed is going to be used.
5. Click More options and define if the attribute should be required or optional. If an attribute can only be mapped to one of a selection of attributes, enter the options one by one – or enter multiple in one go, separated by a comma or a different delimiter. Note that the option names must also match exactly the names of the options on the marketplace where the product feed is going to be used. Once you have added all attributes, click Save.
6. To change the order of the attributes, drag and drop them using the six-square icon. Click Update.
7. Go to the Mappings page and map your attributes. Click Save.
8. Go to the Activation page, where you can toggle the Activate setting.
9. Return to the Feed settings page and click Generate feed. Once generated, the URL of your product feed is shown on the Setup page, where it can be copied and used on supporting marketplaces.

Set up a feed

Product feeds can be added and edited on the Product feeds page, which is accessible by going to Products, Product feeds in the left-hand side menu on ChannelEngine.

Feed operations

As well as adding a feed with the Add feed button, you can see an overview of your existing feeds on the Product feeds page – and perform a few actions.

To find a specific feed, use the search bar at the top of the page or navigate through the pages. Each page lists up to 20 product feeds.

• Name - the name of the feed.
• URL - the URL where the feed can be downloaded from.
• Type - the type of feed (CSV, JSON, or XML), and if it is a leading or additional feed.
• Most recent import - the timestamp of the latest import of the feed.
• 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 click the Add product feed button, you are asked to input the location of the feed (e.g.: https:docs.google.com/spreadsheets/d/e/somenumbersandletters). Then you need to select the correct delimiter if using a CSV feed (i.e.: what character separates individual columns in the CSV), or the product node if using a JSON or XML feed (i.e.: what tag marks an individual product in the feed).

Click 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 XML 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 click Continue after setting the correct delimiter (for a CSV feed) or product node (for an XML or JSON feed), the feed settings page appears.

• 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, etc.
• 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 international locale. This means that for numbers (e.g.: prices, dimensions, etc.), ChannelEngine expects a period as the decimal separator (e.g.: EUR 9.95). If your feed uses 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 for the products grouped by the parent SKU – without a parent product available in the feed. The setting only applies to a leading feed.
• Generate grandparent products - if this setting is enabled, ChannelEngine automatically generates grandparent products for the products grouped by the grandparent SKU – without a grandparent product available in the feed. The setting only applies to a leading feed.

• Product feed status - by default, product feeds are set to Inactive. If this setting is enabled, the feed status changes to Active, prompting ChannelEngine to initiate the import of the product feed. To pause the import and deactivate the product feed, disable this setting.

Mapping feeds

Below the feed settings, you can find the feed mappings that must be configured to ensure the accurate import of products – as well as their corresponding content into ChannelEngine. Follow the recommendations below to map your attributes effectively considering the three distinct sections: ChannelEngine attributes, stock locations, and custom attributes.

Mapping columns

In the mapping section, you are presented with the following overview:

1. Attribute name - lists the name of the attribute on ChannelEngine. For example, in the ChannelEngine attributes section, you see ChannelEngine-specific attributes, such as Name, Description, and Merchant product number.
2. Center column - shows the mapped attribute from your feed. E.g.: Merchant product number may be mapped to the SKU attribute from your feed. In the initial load of the feed, suggested attributes are highlighted in green.
3. Right column - shows the preview of a specific value for that attribute. You have the option to preview the first ten items found in the feed by selecting an example from the dropdown menu next to Preview.
   NB: use the search bar above to search for a specific attribute or stock location.

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

• Not mapped - clear value - useful when the attribute should have a fixed value. The fixed value can be mapped on each marketplace's Mappings page on ChannelEngine.
• Not mapped - keep value - useful when another product feed already maps this attribute.

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 marketplace.

ChannelEngine attributes

You can map your attributes to ChannelEngine-specific attributes. These include the most essential attributes required by a marketplace to create a viable product. E.g.: Name, Brand, GTIN, etc.

Stock locations

If you make use of the stock locations feature, you can map your stock attributes according to specific stock locations you have set up on ChannelEngine. E.g.: StockNL for the stock location Het warenhuis. If you have a single stock location, simply map your stock to the Default warehouse attribute.

Custom attributes

There is also an option to add and map your own custom attributes, such as Package height or Collection.

Click Custom attributes to see a list of available attributes that can be used. Attributes highlighted in green are already mapped to a ChannelEngine attribute or custom attribute. Attributes in orange indicate they have not been mapped yet. You can toggle the Show unmapped only setting to display only unmapped attributes.

Keep in mind that it is possible to add an attribute as a custom attribute that is already used in another attribute. To learn how to remove custom attributes that have already been added, check out the article ChannelEngine: custom attributes.

Required, recommended, and optional attributes

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 marketplaces like this is much harder and more time-consuming.

Attribute	Description	Example
Name	Product name	Black t-shirt with crew neck
Description	Product description	A simple black t-shirt from Sustainable T-shirts Inc.
Price	Product price (incl. VAT/sales tax)	49.95
Stock	Product stock	25
Merchant product number	Your unique product number	192354
GTIN	The product's universal identifier (e.g.: EAN, ISBN, UPC, etc.)	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 recommended to provide the following attributes in your feed.

Attribute	Description	Example
Catalog price	MSRP (incl. VAT/sales tax)	59.95
Purchase price	Product purchase price (excl. VAT/sales tax)	35.00
VAT %	VAT/sales tax 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 attributes are not required, although in some situations they may be conditionally required (e.g.: MerchantGroupNo).

Attribute	Description	Example
Parent SKU	The Merchant product number of the parent product, connecting parent and child products	192350
Grandparent SKU	The Merchant product number of the grandparent product, connecting grandparent and parent products	192
Details	The product's details	A simple t-shirt. Color: black. Brand: Sustainable 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 attributes might be added to the feed. These attributes 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 an attribute from your product feed. When you delete an attribute, ChannelEngine removes the value from that attribute during the next feed import.

Formatting and encoding

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> 

JSON

For JSON you need to include a backslash ( \ ). 

"Description": "Basic \" t-shirt met lange mouwen. Het model valt aansluitend en heeft een petrol kleur."

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 may appear in your 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 GTIN are set to null (empty).
• Values, including custom attributes, 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

Validation report

To access a product feed's Validation report, go to Product feeds and click Report. The Validation report page lists the Import history and Validation report sections.

Import history

You can then see the Import history graph, showing the number of products with the statuses Inactive, Unchanged, Updated, and New for that specific feed.

Product statuses are stacked on top of one another. By hovering over each node on the graph, you can see the exact number of products with a certain status. E.g.: Updated.

If you see spikes or plunges, it means that the number of products with a certain status has gone up or down correspondingly. E.g.: if you introduce updates to your product content, the number of products with the status Updated goes up to reflect this change, and the number of products with the status Unchanged goes down.

The Import history section also displays:

• When the most recent import was done. E.g.: 15 minutes ago.
• What the result of that import was (i.e.: the import status). E.g.: Success, Partial success, Fail.

Validation report

Below the Import history section, you can find the Validation report – which lists any issues that were found upon validation. E.g.: 'GTIN: not a valid GTIN [sic] number'; 'Product GTIN is missing in the feed'. You can view the complete list of issues by clicking the error and expanding the list.