Product Catalog Setup

The product catalog is your starting point for all product recommendations. It contains all your products and descriptions and needs to be loaded into Recommendations on a regular basis. For instance, retailers with an e-commerce website using a shopping cart/CMS software first need to do an export from their CMS and then load that file into Recommendations. Publishers may use RSS feeds.

You may have multiple files to load, depending on the location or language. Or your products might come from different sources and as such generate multiple files to import. The main thing to pay attention to is that all these files must have the same format as they are all imported into one single scheme.

In the following sections we explain why and how you have to set up your product catalog feed.

Note: Please get in touch with your Marigold team who will help you set up your catalog correctly. This section will help you prepare your product catalog feed correctly.

Catalog files management

Before Recommendations can generate graphical product selections in the form of Smart Content for websites and personalized emails, or show the right products to the right audience through the Smart Audiences feature, it needs to have access to a product catalog and be able to import it. This product catalog, also called 'product feed', is a set of files which are usually automatically exported by your Content Management System (CMS) on a regular basis, and made publicly accessible. Recommendations then automatically imports these files at regular intervals. Recommendations supports the following standard formats: CSV, XML and JSON.

The configuration of the export is independent from Recommendations and has to be done on your side before you start using Recommendations.
Most of the time standard exports, which are already in place, are reused : Google Shopping, Shopzilla, etc.

The product catalog is updated once a day. However, if an unforeseen update or more regular updates are required, you can launch the update immediately by clicking the Update Now button.

Note: When updating your product catalog, it's important to know that already existing Smart Content is cached, and will not immediately show updated prices, discounts, etc.
Only after the Recommendations synchronization time span has passed (by default each 24 hours), the cached content gets updated.

At Marigold, we can activate a setting for you that makes it possible to clear the cache and reflect your product catalog changes immediately^(*) in your Smart Content after updating the catalog.
^(*) Be aware that clearing the cache may take a while, depending on the amount of cached Recommendations.
To have this setting activated by us, please make a request through a Support ticket.

For example : A Smart Content block showing shoes with a price of €120 are now on discount at a price of €110.
You update the product catalog to reflect the discount price, and want this new price to be immediately visible in your Smart Content, so contacts directly see the updated price.

Note that newly added products are never cached, and will show up in the Smart Content after doing an update.

Domain of your shop — The domain where the ecommerce website is hosted (eg. https://paranasolution.selligent.com/).

Logo — The URL of the logo (not required).

Catalog files — This is the file containing the product catalog. It can be a CSV, XML or JSON file. The catalog files need to be stored on a publicly accessible URL. All major protocols are supported such as HTTP, HTTPS, FTP, FTPS and SFTP. If required, it can be user and password protected.

Note: You can use different catalog files to build your product catalog and even use different files for different languages (not mandatory). This might be necessary when you have different products for different countries or the product descriptions are language dependent.

Click the Add another file button to add an additional file.

Note: Ensure all files have the exact same format!

Catalog files format — CSV, XML, JSON. Depending on the selected type, different options are available in the following sections.

Product Catalog field types

Mandatory fields

The exported feed needs to contain the following minimum information for each product for the catalog to be successfully imported :

Unique ID — The identifier of a product inside the catalog. This value needs to be unique.
Ideally this ID should be found easily on product pages, such as inside the URL (https://my-shop.com/products/blue-jeans-p001.html?variation=2, where p001 is the Unique ID).
Page URL — The exact URL to reach the product page. It's recommended that this URL is unique, but it's not mandatory.
Image URL — The exact URL of the product picture. This picture can be in any format (preferably jpg or png).
- The picture dimensions need to be in line with the picture size to be used in your Smart Content.
  For example: having 100px by 100px images in your feed, while you want to display large retina-compatible pictures in your Smart Content will lead to poor quality images inside generated Smart Content blocks.
- If you put links to high-definition images in your feed but you want Smart Content with much smaller images (of variable sizes), we can take care of optimizing, scaling and hosting your images with a powerful CDN. Please contact your Marigold team if this is something you need.

Optional fields

The three fields described above will only allow a very basic graphical configuration and will not allow any filters to be configured in Smart Content. A standard product feed usually contains the following properties for each product :

Title — The title given to the product. This text needs to be short (~50 characters) as it will automatically be placed under the product picture inside Smart Content if this option is selected.
Subtitle — Same as the title, but can be longer (~100 characters).
Description — The description of the product can be longer. Like the two fields above, it can contain HTML tags, which will be stripped at import time.
Price — The base price of the product which will be displayed to the visitor, before any applied discounts. The currency is not important here as it's set in other optional fields.
Recommendations tries to detect a numerical value in this field.
For example: If the field contains "10Recommendations", the parsed value will be 10. If the field contains "Recommendations10", the value will not be parsed and the price of the product will not be available.
Sale price — The price at which the product is sold (after any applied discounts). In case one or more discounts are applied to the product, the sale price is lower than the price.
Category — The category to which the product belongs.
Quantity — The number of products in stock.
Type — The type of the product, similar to category, usually segmenting products into fewer groups of larger amounts of products.
Brand — The brand of the product. If it's activated, it appears in Smart Content at the bottom of the text description, after the title, description and price.
Color — The color of the product (if it's a parameter that makes sense).
Main personality — Mainly for movies (actor/producer) or books (author), used mainly for filtering purposes.

Custom fields

Recommendations can deal with any number of fields per product. Custom parameters can be included and will be used by Recommendations in different ways (displaying custom content inside Smart Content, setting up advanced filters). Here are some examples of common fields that are included in product feeds :

Availability — Whether a product can be bought or not. It can be any value and is mainly used in filters.
Condition — Whether the product is new, refurbished, etc.
Manufacturer — The manufacturer of the product.

Your product feed export should be accessible at a publicly reachable URL (HTTP(S) or (S)FTP), but can be password-protected. Once an export is configured on your site, you can start configuring the import in the following section.

Product feed formats

The most common product feed formats are supported. In this section, you will find examples of possible formats you can use for your product feed.

CSV format

Your entire product feed can be contained :

in a single file
in multiple files, which are all part of the same feed.
in multiple files, for which each one of them represents a specific language and/or location.

If you have multiple files, all of those need to have the exact same format (same number and order of columns).

CSV product feed example :

Once your files are exported to a server accessible via (S)FTP or HTTP(S), your files will be downloaded by Recommendations and the columns defined will be mapped to column names in Recommendations.

CSV feed-specific settings

For CSV product feeds, the following specific settings need to be taken into account :

The field delimiter

The character that stands between each field.
In the example above, the character is: | (pipe).
You are allowed to use any of the following: '\t' (tab), '|' (pipe), '%' (percentage sign), ',' (comma) or ';' (semicolon).

The type of quotes around fields

In some CSV files, quotes are used around fields (eg. "field 1"|"field 2").
You can use ' ' (single quotes) or " " (double quotes).
Although it's safer to not use them at all, when using the right delimiters.

The encoding

The encoding used in your product feed files. You can find or tune the encoding in your text editor.
By default, if you're on a Linux or MacOS system, leave it to UTF-8. If you're on a Windows system and you see strange characters appearing in your Smart Content, set it to Latin1.

CSV fields configuration

Your CSV column names — Enter the name of the columns as they exist in the CSV file, in the exact same order. Use the same separator as used in the file.

Column properties — For each column defined in the CSV file, you have to set the right column name for Recommendations to interpret the data correctly. This creates the mapping between the names of columns in the CSV file which is imported and the values Recommendations uses in filters and display of product recommendations.
Following options are available by default :

Unique ID — The unique identifier of the product.
Page URL — URL of the product/article page.
Image URL — URL of the main image to be used inside Smart Content.
Title — The title of the product (the main title used under the product image).
Subtitle — The secondary title.
Category — The category the product belongs to.
Price — The main price, or the original price if the product also has a sale price.
Description — The description of the product (usually longer than the title).
Color — The color, if applicable.
Sale price — The sale price (if present, the original 'price' will be displayed as struck-through).
Quantity — How many items are available in stock (if appropriate).
Main personality — E.g. actor, author, etc.
It's displayed at the very bottom, underneath the product image.

You can also add custom fields. “Custom fields” are just other data fields, which can be displayed under product images in Smart Content. They can also be used as filters (e.g. the product's “collection” has to be equal to “Summer2018”).

For every column mapped, additional options can be set. Some options manipulate data at catalog import, others are used for specific purposes (return values with a specific name via the API). Check the 'Options' box to display the options available for this field :

This field is an array of values — When a field contains an array, e.g. <sizes>[S,M,L,XL]</sizes>. Those will be read and stored as an array rather than a string.
This field is a number (not text) — E.g. <online_stock>76</online_stock>. By making the value numeric, you can use it in filters using operators such as greater than, between X and Y, etc.
This field will be sent with API responses as — When this option is selected, the data is sent in JSON format through the API. This way, website developers can display the information how they want : e.g. parsing JSON.
An optional field name can be set.
In this text field replace — A specific string can be replaced by something else.
This field is an Image URL — When a field is marked as Image URL, it can be selected in the Smart Content Email Graphics Editor as image URL in the image settings of a Catalog-image placeholder object.
Note: You can only mark a maximum of 5 fields as Image URLs (i.e. the default product image and 4 additional catalog fields).

Additionally, the following can be set per field:

Active — To indicate the field is taken into account for the import.
Index keywords — This places an index on this field and will then be used for keyword similarity checks . Products in the catalog with similar keywords as the product/article currently displayed will then be returned as recommended articles for the reader.

Below the 'Column Properties', the following settings can be configured :

Field delimiter — The delimiting character between fields in the CSV file. The choice can be made between ',' (comma), '|' (pipe), ';' (semicolon), '%' (percentage sign), space or tab.

Quote type around fields — Fields can be placed between quotes. If this is not the case, leave the value to 'nothing'.

Type of encoding used in the source file — UTF8, US-ASCII, Latin1, etc.

Skip first line — Flag this option if the first line contains the column names.

Catalog file access Username — The username to access the source file.

Catalog file access Password — The password to access the source file.

Currency symbols — Depending on the language and the location, different currency symbols can be used. You can put them left or right of the number.

Default mail language — If the language that's used in personal user data (*) is not set in the Product Catalog, the default mail language will be used when set.

(*) Note: Personal user data refers to main user list data that gets synchronized from Marigold Engage to Recommendations daily.

Catalog import filters — Filter out data from the import file based on one or more conditions being true. For example, filter out all products that don't have an image URL.

Additional properties — In this section you can create additional boolean attributes for your products based on the value of a specific field.
Example : The property 'MyRegion' is true if the field 'locale' contains 'be'.

XML format

As with the CSV format, you can use one or more files for XML product feeds, with or without language/location parameters.

Note: The big difference with CSV files is that for XML files the products don't need to have all the attributes defined.
For example if a property 'collection' is defined, but some items do not contain a 'collection' field, these items will still be added to the product catalog.

Copy

XML product feed example :

<?xml version="1.0" encoding="UTF-8"?>
<products>
    <product>
        <identifiant_unique><![CDATA[p0001]]></identifiant_unique>
        <url_produit><![CDATA[https://www.my-shop.com/products/nice-pants-p0001.html]]></url_produit>
        <url_image_1><![CDATA[https://www.my-shop.com/static/img/p0001.jpg]]></url_image_1>
        <couleur><![CDATA[bleu]]></couleur>
        <brand><![CDATA[the best brand]]></brand>
        <price><![CDATA[199]]></price>
    </product>
    [...]
</products>

Each product in the feed needs to be encapsulated in the same XML Tag (<product> in the example above) which specifies the tag name of the highest level object and which contains all the product information for one product. In the previous example, <products> contains a list of all <product> sub-objects, each one containing all the information for a specific product.

In XML, field values can have simple types such as strings (chains of characters) or numbers.
Another (special) field type is the array of values. A field can be an array of several values rather than a single value. It's useful for array fields such as <available_sizes><![CDATA[35,36,37,38,39,40,41,42]]></available_sizes>.

XML feed-specific settings

Multi language support — When this option is selected, you can match a language symbol in the URL of the product with a language symbol in the XML.

Base XML Tag — This is the main tag in the XML, e.g. “product” if the content of each item is enclosed in <product></product>.

Product Properties — In here you can link the fields used in Recommendations to the tags used in the XML.

Catalog file access Username — The user name to access the source file.

Catalog file access Password — The password to access the source file.

Currency symbols — Depending on the language and the location, different currency symbols can be used.

Catalog import filters — Filter out data from the import file based on one or more conditions being true.

JSON format

A typical JSON feed works in a similar way as the XML feed described above.

Copy

JSON product feed example :

[
    {
        "product_id": "p001",
        "product_url": "https://www.my-shop.com/products/nice-pants-p0001.html",
        "product_first_image": "https://www.my-shop.com/static/img/p0001.jpg",
        "product_master_category_name": "category 1",
        "product_created_at": "2014-02-04 08:29:23",
        "product_brand": "the best brand",
        "product_name": "first product"
    }
    ...
]

The field options used in JSON are the same as the ones described in XML. If you want to have feeds in many languages using JSON files, you have to create one file per language/location.

Note: Just like for XML, JSON product feeds don't require all the attributes to be defined.

JSON feed-specific settings

Product Properties — In here you can link the fields used in Recommendations to the tags used in the JSON.

Catalog file access Username — The user name to access the source file.

Catalog file access Password — The password to access the source file.

Currency symbols — Depending on the language and the location, different currency symbols can be used.

Catalog import filters — Filter out data from the import file based on one or more conditions being true.

Note: For all catalog formats (CSV, XML, JSON) , the following fields are required fields : product ID, page URL and image URL.

Also make sure that :
- the keys (column names) used are identical for all your languages, taking proper casing into account
(eg. when for English 'image_url' is used, for German don't use 'Image URL' but use the same key 'image_url')
- no empty values are set (values must be set in all languages for all the required fields)

Note: It's possible to use parameters in the product URL and image URL in your catalog file.
For example https://www.paranashop.com/mens-clothing?ProductId=1234567&Color=16

Importing a product compatibility matrix

In order to use the 'Compatible' algorithm in Web Smart Content, you need to provide Recommendations with a CSV file containing compatibilities between products. Recommendations will automatically use the relationships defined in this file to display compatible products when the user lands on a product page from one of the products mentioned in the file.

Your "related products" file is a text file which needs to contain a compatibility between two products on each line.

For example : If you have 3 products in your catalog (with unique IDs "A", "B" and "C"), and you want products "A" and "B" to be compatible, products "B" and "C" to be compatible, and products "A" and "C" NOT to be compatible, you would need a file with the following content :
A;B
B;C

Note: Once this file is prepared, contact your Marigold team to get the instructions to upload it.

Frequently asked questions

What about the import frequency ?

Recommendations will automatically update the product catalog once a day, but it can be adapted easily to your exact needs.

What about internationalization (multiple languages/locations) ?

If your website is available in several languages, there is nothing to worry about. Recommendations natively supports shops with multiple languages and locations. We import your catalog files in different languages and render Smart Content product recommendations according to parameters you define (typically URLs or domain names).
The answer is the same if all your shops are available under different domains. As long as the Unique IDs of your products are the same on all your shops (even if their parameters such as title, price and availability are different), everything works as described above.
If you have specific requirements, do not hesitate to contact us.

Which CMS systems are supported ?

If you are using an installable CMS (Adobe Commerce, Prestashop, WooCommerce, Hybris, Websphere), or a cloud-based CMS ( Shopify, VTEX), or if you developed your own e-commerce site in any programming language, you will be able to use Recommendations.
There is no reason why you would not be able to export a product feed. A product feed is simply an export of your product database into a file with the format and content you define yourself. Most CMS systems provide extensions to export feeds in a standard format (Google Shopping, Shopzilla, standard CSV, etc.), and we support all of those.

Note: If you can't find a way to do the export, you can always contact your Marigold team for help.

Example : Configuring the product catalog