> For the complete documentation index, see [llms.txt](https://fredhopper.gitbook.io/product-discovery/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fredhopper.gitbook.io/product-discovery/sending-and-managing-product-data/what-is-the-items-api/working-with-items/items.md). # 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. {% hint style="warning" %} If a category tree has been defined for a catalogue version, the categories attribute becomes mandatory {% endhint %} ### 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](https://github.com/Attraqt/product-discovery-documentation/blob/main/new-docs/sending-and-managing-data/sending-product-data/items-api/how-to-work-with-items/item-catalog/README.md) | | context | string | no | Context (store id, private sales...). Can only include alphanumeric characters, underscores and hyphens. | | type | string | yes | see [itemSchema](https://github.com/Attraqt/product-discovery-documentation/blob/main/new-docs/sending-and-managing-data/sending-product-data/items-api/how-to-work-with-items/item-schema/README.md) | | 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**](/product-discovery/sending-and-managing-product-data/what-is-the-items-api/working-with-items/item-schema.md)**.** Let's say your item schema has the following attributes: ```javascript [ { "name": "title" "type": "TEXT" }, { "name": "price" "type": "INTEGER" }, ] ``` An item attributes should look like this. ```javascript { "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](https://github.com/Attraqt/product-discovery-documentation/blob/main/new-docs/sending-and-managing-data/sending-product-data/items-api/how-to-work-with-items/item-catalog/README.md) | | context | string | no | Context (store id, private sales...) | | type | string | yes | see [itemSchema](https://github.com/Attraqt/product-discovery-documentation/blob/main/new-docs/sending-and-managing-data/sending-product-data/items-api/how-to-work-with-items/item-schema/README.md) | | 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: `_`