Managing item catalogs

There are two kinds of feeds for recommendations in Synerise:

  • The item feed is used by item recommendations
  • The metadata catalog is similar to the item feed, but instead of actual products, the items in this catalog are attributes. This is used to create section and attribute recommendations.

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]+[\-_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 whitespace 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": "Xa34ad3d",
    "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

Item feed

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

  • 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.
    Before you submit your Google Merchant feed to Synerise, you can use external XML schema validator tools to make sure that the file does not contain errors.
Important: An item may represent a product, an article, a movie, an entry in documentation, and so on.
WARNING: We recommend using Google Merchant XML instead of XML files due to the size limits (an XML file cannot exceed 10 MB).

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 feed


  • 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 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: You can add multiple custom attributes to item feed. All custom attributes must be preceded with a c: prefix.
Important: Attribute regarding availability will be automatically changed to false for the items which have been removed from latest feed version.

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 Item attribute remarks
additional_image_link additionalImageLinks Array of strings
additional_product_type 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

Metadata catalog


The metadata catalog is used to enrich the standard item feed or catalog for section page and attribute recommendation campaigns. This catalog must contain the itemId column, which is the unique value of the attribute. For example, in a catalog that stores categories (category is an attribute), the values in the itemId may include “Hoodie”, “Longsleeve”, “T-shirt”, and so on.

Typically, the catalog contains at least an image that is used as the recommendation tile and the URL of the recommended attribute or category. It can also store data such as descriptions of the attribute (“This category includes the comfiest hoodies”), an alternative title that you want to show in the recommendation (“Comfy hoodies”), and any other data that your implementation requires.

This catalog is usually uploaded as a CSV file.

Metadata for attribute recommendations

Attribute recommendations do not recommend items from the feed or catalog. Instead, they recommend attribute values. When you recommend attribute values, the catalog must contain at least the itemId (the attribute value) and an image link.

Metadata for section recommendations

Section page recommendations recommend both attribute values and items within those values. The metadata catalog enriches the sections that correspond to attribute values (for example brands or categories).

Example:

An attribute recommendation is used to recommend categories. Each category value (for example, “Hoodies”) in the recommendation frame should be displayed with an image that illustrates it.

The link to the image (such as a hoodie for the “Hoodie” category) must be provided in the metadata catalog so it can be shown in the recommendation. You can then use that image in the recommendation frame as a tile that links to the “Hoodie” category page. In the recommendation response, this is what a single recommended category could look like:

        {
            "itemId": "Hoodies",
            "image": "/yourcdn.com/hoodie.png"
            "link": "/yourstore?category=hoodies"
            ...//  additional data from the metadata catalog, if you added some
        },

Example:

An attribute recommendation is used to recommend brands: BRAND1, BRAND2, BRAND3.

Each brand needs an image which represents it, and a link to that image is stored in the metadata catalog, where the brand name is the itemId. When you make a recommendation request and all three brands are recommended, the returned data will be similar to this:

{
    "data": [
        {
            "itemId": "BRAND1",
            "link": "/yourstore?brand=brand1",
            "image": "/yourcdn.com/brand1.png"
            ...//  additional data from the metadata catalog, if you added some
        },
        {
            "itemId": "BRAND2",
            "link": "/yourstore?brand=brand2",
            "image": "/yourcdn.com/brand2.png"
            ...//  additional data from the metadata catalog, if you added some
        },
        {
            "itemId": "BRAND3",
            "link": "/yourstore?brand=brand3",
            "image": "/yourcdn.com/brand3.png"
            ...//  additional data from the metadata catalog, if you added some
        }
    ]
}

😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker