Items

Definition

Post an item

The Post method will upsert an item in the catalogue. If the item already exists, it'll be updated. Unlike the patch, attributes are fully replaced. The whole item attributes must be sent otherwise only the attributes passed in the body will be stored and used for enrichment. This method checks the presence of mandatory attributes and type matching as defined in the item schema.

If a category tree has been defined for a catalogue version, the categories attribute becomes mandatory

Patch an item

Patch an item is used to update only some attributes of the item. Unlike the upsert, attributes aren't fully replaced but only the updated one. This method is mainly used to change frequently updated attributes e.g: quantity. This method checks only type matching.

Delete an item

Delete an item is used to remove an item from the catalogue. No schema validation is performed for this method.

Variants

If the item is a variant, it's always related to a parent. Parent's attributes will be automatically used for tag computation. Insert or patch the variant with theses attributes, do not include parent's attributes.

Structure

Json item

To create or modify items, these elements must be sent in JSON as an array. Each element must respect the following basic structure.

Field name	Field type	mandatory	description
id	string	yes	unique item id. Can not be empty and can only include alphanumeric characters, colons, underscores and hyphens.
catalogVersion	int32	yes	see catalog
context	string	no	Context (store id, private sales...). Can only include alphanumeric characters, underscores and hyphens.
type	string	yes	see itemSchema
timestamp	string	no
attributes	object	yes	see attributes below
parentId	string	no	Parent item, if item is a variant
tenant	string	yes
environment	string	yes

Attributes

The attributes field is a key-value object of every attribute. These customizable fields are defined in the item schema api. Each attribute must follow the different types defined in your item schema.

Let's say your item schema has the following attributes:

[
    {
        "name": "title"
        "type": "TEXT"
    },
    {
        "name": "price"
        "type": "INTEGER"
    },
]

An item attributes should look like this.

{
    "title": "My Product",
    "price": 1000
}

Json Item ID

To delete items, as well as in the creation API return, the format used is a Json called jsonItemId described below.

Field name	Field type	mandatory	description
id	string	yes	unique item id
catalogVersion	int32	yes	see catalog
context	string	no	Context (store id, private sales...)
type	string	yes	see itemSchema
tenant	string	yes	Based on query parameter
environment	string	yes	Based on query parameter

Validation

Additional validation will be applied to each item:

• item Id must match regex "^[\w\-:]+$" i.e. item id must only contain Latin letters (uppercase and lowercase) a-z, A-Z, digits: 0-9, hyphens: -, and colons: :

• item context must match regex "^[\w\-:]+$" i.e. item context must only contain Latin letters (uppercase and lowercase): a-z, A-Z, digits: 0-9, hyphens: -, and colons: :

• Parent products must not have a parentId

• Variant (or secondary) products must have a parentId. This applies if the data model has a hierarchy.

• attributes must be defined in item schema

• LocalizedText should contain valid locale

• If categoryTree is defined, items should have a “categories” attribute categories attribute should only contain values from categoryTree categories must not be empty unless it’s a patch

FHR data model validation

The query parameter fhrValidation=true can be added to enforces Fredhopper specific validation to the items API. This includes the following additional checks to the schema:

• Each item must contain at least one attribute

• For int attributes: Greater or equal to zero

• For float attribute: Greater or equal to zero

• For object/objectlists:

  • value_ids are lowercased with only [a-z0-9_]+ i.e. value_id must only contain lowercase Latin letters: a-z, digits: 0-9, and underscores: _