# Items

> Source: https://docs.recombee.com/api/items

> For the complete documentation index, see [llms.txt](/llms.txt).

# Items

The following methods allow you to maintain the set of items in the catalog. The items are specified using their ids, which are unique string identifiers matching _^\[a-zA-Z0-9\_-:@.\]+$_, i.e., they may consist of digits, Latin letters, underscores, colons, minus signs, at signs, and dots. Item ID `undefined` is forbidden.

put

## Add Item

Adds a new item of the given `itemId` to the items catalog.

All the item properties for the newly created item are set to null.

```js
client.send(new requests.AddItem(itemId));
```

---

### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

ID of the item to be created.

---

### Responses

201

Successful operation.

---

400

The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

409

The `itemId` is already present in the item catalog. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

delete

## Delete Item

Deletes an item of the given `itemId` from the catalog.

If there are any _purchases_, _ratings_, _bookmarks_, _cart additions_, or _detail views_ of the item present in the database, they will be deleted in cascade as well. Also, if the item is present in some _series_, it will be removed from all the _series_ where present.

If an item becomes obsolete/no longer available, it is meaningful to keep it in the catalog (along with all the interaction data, which are very useful), and **only exclude the item from recommendations**. In such a case, use [ReQL filter](https://docs.recombee.com/reql) instead of deleting the item completely.

```js
client.send(new requests.DeleteItem(itemId));
```

---

### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

ID of the item to be deleted.

---

### Responses

200

Successful operation.

---

400

The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

The `itemId` is not present in the item catalog. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the item was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

## List Items

Gets a list of IDs of items currently present in the catalog.

```js
const result = await client.send(new requests.ListItems({
  // optional parameters:
  filter: 'price > 50',                                   // string
  count: 10,                                              // integer
  offset: 0,                                              // integer
  returnProperties: true,                                 // boolean
  includedProperties: ['title', 'price', 'publishedAt'],  // array
}));
```

---

Calls Limit Per Minute

100

---

### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

filter

String

Located in: **query**

Required: **No**

Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter items to be listed. Only the items for which the expression is _true_ will be returned.

---

count

Integer

Located in: **query**

Required: **No**

The number of items to be listed.

---

offset

Integer

Located in: **query**

Required: **No**

Specifies the number of items to skip (ordered by `itemId`).

---

returnProperties

Boolean

Located in: **query**

Required: **No**

Since version: **1.4.0**

With `returnProperties=true`, property values of the listed items are returned along with their IDs in a JSON dictionary.

Example response:

```
  [
    {
      "itemId": "tv-178",
      "description": "4K TV with 3D feature",
      "categories":   ["Electronics", "Televisions"],
      "price": 342,
      "url": "myshop.com/tv-178"
    },
    {
      "itemId": "mixer-42",
      "description": "Stainless Steel Mixer",
      "categories":   ["Home & Kitchen"],
      "price": 39,
      "url": "myshop.com/mixer-42"
    }
  ]
```

---

includedProperties

Array

Located in: **query**

Required: **No**

Since version: **1.4.0**

Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.

Example response for `includedProperties=description,price`:

```
  [
    {
      "itemId": "tv-178",
      "description": "4K TV with 3D feature",
      "price": 342
    },
    {
      "itemId": "mixer-42",
      "description": "Stainless Steel Mixer",
      "price": 39
    }
  ]
```

---

### Responses

200

Successful operation.

```
[
  "item-1",
  "item-2",
  "item-3"
]
```

---

404

If present, `filter` contains a non-existing item property.

---

delete

## Delete More Items

Deletes all the items that pass the filter.

If an item becomes obsolete/no longer available, it is meaningful to **keep it in the catalog** (along with all the interaction data, which are very useful) and **only exclude the item from recommendations**. In such a case, use [ReQL filter](https://docs.recombee.com/reql) instead of deleting the item completely.

```js
const result = await client.send(new requests.DeleteMoreItems(filter));
```

---

Since version

3.3.0

---

Calls Limit Per Minute

1000

---

### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **3.3.0**

ID of your database.

---

filter

String

Located in: **body**

Required: **Yes**

Since version: **3.3.0**

A [ReQL](https://docs.recombee.com/reql) expression, which returns `true` for the items that shall be updated.

---

### Responses

200

Successful operation.

```
{
  "itemIds": [
    "item-42",
    "item-125",
    "item-11"
  ],
  "count": 3
}
```

---

400

Invalid filter.

---