Managing item catalogs

There are two ways to import an item feed to Synerise:

Important: An item may represent a product, an article, a movie for VOD, an entry in documentation, and so on.

Create a catalog, prepare an XML file, and set the automatic import of the feed to a catalog (the imported element is later referred to as an item catalog).
Import Google Merchant feed.

WARNING: We recommend using Google Merchant XML instead of XML files due to the size limits (an XML file cannot exceed 10 MB).

Requirements for item catalogs

Limitations

The name of the item catalog must be an alphanumeric string without any special characters nor whitespaces, following this regex pattern: [a-zA-Z0-9]*.
Item attribute names must be an alphanumeric string without whitespaces, following this regex pattern [-_a-zA-Z0-9]*.
Item attribute string values must be alphanumeric. They can’t contain following characters:
- " - quotation mark
- ' - inverted comma
- . - dot
- , - comma
- space or any white character
Therefore, complex.name is forbidden and you should rather use camelCase: complexName (preferred) or underscore format: complex_name.
Synerise accepts any properly formatted JSON which contains itemId and with proper key names. Later, item attributes are being returned by the API without changing or parsing values, which also applies to HTML/XML tags as values. You should handle the raw data retrieved from API in a way that will avoid the risk of XSS attack.
Attribute names are case sensitive.

Format

The format of an item is a JSON. Each object represents an item with its attributes, for instance:

{
    "itemId": "Xa34ad",
    "intAttribute": 5,
    "floatAttribute": 2.5124,
    "stringAttribute": "asfdqw",
    "timestampAttribute": 1356846157,
    "booleanAttribute": true,
    "arrayOfStringsAttribute": ["A", "B", "C"],
    "nestedObject": {
        "a": 1,
        "b": "value"
    },
    "nestedObjectsArray": [
        {
            "x": "y"
        }
    ]
}

Accepted values of attributes

string: "foo"
integer: 12
float: 12.34
boolean: true/false
nested objects: { "sub": { "a1": "v1", "a2": "v2" } }
array (of strings, integers, floats, booleans, nested objects, arrays): ["foo", "bar"]
timestamp: should be formatted as Unix timestamp, for example, 1356846157
date: string dates are not interpreted/parsed - you should add a field which is formatted as a timestamp

Unique identifier

Each item (each JSON document) must contain an itemId field which is a reserved key used as a unique item identifier. Its value type must be a string and it’s case sensitive. As itemId is an item identifier it is specially treated:

It is always returned by search API
It is always returned by recommendations API
Events (especially page.visit and transaction.charge) should contain matching itemID

Special field

category is a special attribute which is used to define the hierarchy of categories which an item belongs to. It must have the following format:

X > Y > Z

Where X is a top level category and Z is the lowest category level. For example, Electronics > Phone and Smartphones > Smartphones. Category levels should be joined with > (literally space>space). When you have an item which belongs to more than one category, you can pass the additionalCategories field in the following format:

"additionalCategories": ["A > B > C", "D > E > F"]

Both category and additionalCategories are used when you filter by categories.

Requirements for Google Merchant

Build your feed according to Google Merchant Center Help recommendations. Synerise supports the tags described there.
In the XML Prologue, define two namespaces as follows: "xmlns:g="http://base.google.com/ns/1.0" xmlns:c="http://base.google.com/cns/1.0"
All tags that are defined by Google Merchant Center Help must be preceded with a g: prefix. The only tags that do not use the prefix are: <title>, <name> and <link>, and your custom tags that are not defined by Google Merchant Center Help.
The list of the obligatory tags (written in angle brackets):
- g:id
- title
- g:availability
- g:product_type
- g:price
- link
- g:image_link

WARNING: It is important to have consistent item ID in the page.view events, transactional events and in the feed, otherwise the recommendation frame will not display them at all or the system will not register the purchase and/or it won’t be counted towards revenue.

Important: XML feeds are converted into item catalog format with default as a catalog name.

Feeds which are in Google Merchant XML format are automatically transformed into items format according to following rules:

Click to see the table

Google Merchant	JSON attribute	remarks
additional_image_links	additionalImageLinks	Array of strings
additional_product_types	additionalCategories	Array of strings
adult	adult	String
availability: String	availability: Boolean	true ~ 'in stock', 'preorder'; false ~ 'out of stock'
brand	brand	String
channel	channel	String
color	color	If an item has more than one color, they must be separated with `/`. The colors are converted into the `colors` array (see next row).
-	colors	Array of strings, contains parsed values of "color", `XML.color.split('/')`
condition	condition	String
content_language	contentLanguage	String
custom_attributes	attributes.attributeName	All elements from `custom_attributes` column are mapped into attributes object and placed on a top level i.e.: `{"(fason,text,,Chusta)","(model,text,,Tortona)","(additionalPrice,text,,\"43.99 PLN\")"}` All elements from `custom_attributes` column are mapped into: "attributes": { "fason": "Scarf", "model": "Tortona", "additionalPrice": { "value": 43.99, "currency": "PLN” } }
custom_groups	attributes.groupName	All elements from `custom_groups` column are mapped into attributes object and placed as objects with the same name on a top level. All elements from a particular group are then moved into newly created objects in a same fashion as custom_attributes i.e.: custom_groups: `{"(\"{\"\"(process_type,text,,SALE_OF_GOODS)\"\",\"\"(market,text,,b2c)\"\"}\",synerise_filtering)","(\"{\"\"(Rodzaj,text,,book)\"\"}\",Rodzaj_Etui)"}` will be mapped into: "attributes": { "synerise_filtering": { "process_type": "SALE_OF_GOODS", "market": "b2c" }, "Rodzaj_Etui": { "Rodzaj":"book" } }
custom_label0 custom_label1 custom_label2 custom_label3 custom_label4	"customLabel": { "1": "value1", "2": "value2" }
description	description	String
gender	gender	String
google_product_category	googleProductCategory	String - joined with ' > ' so i.e. 'X > Y > Z'
gtin	gtin	String
image_link	imageLink	String
item_group_id	itemGroupId	String
kind	kind	String
link	link	String
offer_id	itemId
price_currency	price.currency	'price': {'currency': 'PLN', 'value': 849.00}
price_value	price.value	'price': {'currency': 'PLN', 'value': 849.00}
-	effectivePrice	Number, if (XML.sale_price isDefined) XML.sale_price else XML.price
-	discountAmount	Number, XML.price - calculated.effectivePrice
-	discount	(XML.price - effectivePrice) / price if price <> 0 else 0
product_type	category
sale_price_currency	salePrice.currency	'salePrice': {'currency': 'PLN', 'value': 849.00}
sale_price_value	salePrice.value	'salePrice': {'currency': 'PLN', 'value': 849.00}
sizes	sizes	Array of strings
target_country	targetCountry	String
title	title	String