Item feed in a catalog

You can upload an item feed to a Synerise catalog.

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

• Attribute names are case-sensitive.

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

• The item feed limit for visual similarity recommendation model is 1,000,000 items, regardless of the item feed type.

Item 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"
        }
    ]
}

Attributes

Required attributes

Accepted attribute values

• 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: 2024-01-01T10:00:00Z or Unix timestamp (12345664000) sent as a string

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 a matching itemId

Item availability attribute

If you want to include the item availability attribute (availability) in your item catalog, the attribute’s value must be a boolean.

Category attribute

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.

Attribute best practices

• We recommend using category as the attribute name for item categories, or additionalCategories if an item belongs to multiple categories;
• Attribute names starting with calculated. or inventory. are not allowed.