> ## Documentation Index
> Fetch the complete documentation index at: https://lopiv2-invenicum-25.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Inventory Items

> Manage inventory items with CRUD operations, image uploads, and custom fields

## Overview

Inventory items represent individual assets tracked in your system. Each item belongs to a container and has an asset type that defines its custom fields. Items support multiple images, quantity tracking, custom field values, and market value tracking.

***

## List Items

```http theme={null}
GET /items
```

Retrieve all inventory items across all containers with optional aggregation filters.

**aggFilters** `string`

Comma-separated key:value pairs for filtering by custom field values.

Example: `brand:Apple,condition:New`

```json theme={null}
{
  "data": {
    "items": [
      {
        "id": 1,
        "name": "MacBook Pro 16\"",
        "description": "M2 Max, 32GB RAM",
        "barcode": "123456789",
        "containerId": 5,
        "assetTypeId": 2,
        "locationId": 3,
        "quantity": 1,
        "minStock": 1,
        "marketValue": 2499.99,
        "currency": "EUR",
        "totalMarketValue": 2499.99,
        "lastPriceUpdate": "2026-03-07T10:30:00Z",
        "customFieldValues": {
          "brand": "Apple",
          "condition": "New",
          "serialNumber": "FVFXK3G8Q05N"
        },
        "images": [
          {
            "id": 12,
            "url": "https://storage.example.com/item-1-photo.jpg",
            "altText": "Front view",
            "order": 0
          }
        ],
        "location": {
          "id": 3,
          "name": "Office Shelf A",
          "description": "Main storage area"
        },
        "createdAt": "2026-01-15T08:20:00Z",
        "updatedAt": "2026-03-07T10:30:00Z"
      }
    ],
    "totalItems": 1,
    "totalMarketValue": 2499.99
  }
}
```

**data** `object`

Container for response data

**properties**

**items** `array`

Array of inventory item objects

**item properties**

**id** `integer` *required*

Unique identifier for the item

**name** `string` *required*

Item name

**description** `string`

Detailed description of the item

**barcode** `string`

Barcode or UPC code for market value syncing

**containerId** `integer` *required*

ID of the parent container

**assetTypeId** `integer` *required*

ID of the asset type defining custom fields

**locationId** `integer`

ID of the location where item is stored

**quantity** `integer` *required*

Current quantity in stock (default: 1)

**minStock** `integer` *required*

Minimum stock threshold for alerts (default: 1)

**marketValue** `number`

Current market value per unit (default: 0.0)

**currency** `string`

Currency code (default: "EUR")

**totalMarketValue** `number`

Total value (marketValue × quantity)

**lastPriceUpdate** `string`

ISO 8601 timestamp of last price sync

**customFieldValues** `object`

Key-value pairs for custom field data defined by asset type

**images** `array`

Array of image objects

**image properties**

**id** `integer`

Image ID

**url** `string`

Full URL to the image

**altText** `string`

Alternative text description

**order** `integer`

Display order (0-based)

**location** `object`

Location details if locationId is set

**properties**

**id** `integer`

Location ID

**name** `string`

Location name

**description** `string`

Location description

**createdAt** `string`

ISO 8601 creation timestamp

**updatedAt** `string`

ISO 8601 last update timestamp

**totalItems** `integer`

Total count of items in response

**totalMarketValue** `number`

Sum of all totalMarketValue fields

***

## List Scoped Items

```http theme={null}
GET /containers/{containerId}/asset-types/{assetTypeId}/items
```

Retrieve inventory items filtered by container and asset type.

**containerId** `integer` *required*

ID of the container

**assetTypeId** `integer` *required*

ID of the asset type

**aggFilters** `string`

Comma-separated key:value pairs for custom field filtering

```json theme={null}
{
  "data": {
    "items": [
      {
        "id": 42,
        "name": "iPhone 15 Pro",
        "containerId": 5,
        "assetTypeId": 2,
        "quantity": 2,
        "customFieldValues": {
          "color": "Natural Titanium",
          "storage": "256GB"
        }
      }
    ],
    "totalItems": 1
  }
}
```

***

## Create Item

```http theme={null}
POST /items
Content-Type: multipart/form-data
```

Create a new inventory item with optional image uploads.

**name** `string` *required*

Item name

**description** `string`

Item description

**barcode** `string`

Barcode or UPC for market sync

**containerId** `integer` *required*

Parent container ID

**assetTypeId** `integer` *required*

Asset type ID defining custom fields

**locationId** `integer`

Storage location ID

**quantity** `integer` (default: 1)

Initial quantity

**minStock** `integer` (default: 1)

Minimum stock threshold

**customFieldValues** `string` *required*

JSON-encoded object of custom field values matching asset type field definitions

Example: `{"brand":"Apple","condition":"New"}`

**images** `file[]`

Array of image files to upload. Field name must be "images" for each file.

```json theme={null}
{
  "data": {
    "data": {
      "id": 123,
      "name": "iPad Air",
      "description": "5th generation",
      "barcode": "194253912736",
      "containerId": 5,
      "assetTypeId": 3,
      "locationId": 7,
      "quantity": 1,
      "minStock": 1,
      "customFieldValues": {
        "color": "Space Gray",
        "storage": "64GB"
      },
      "images": [
        {
          "id": 45,
          "url": "https://storage.example.com/uploads/item-123-0.jpg",
          "altText": null,
          "order": 0
        }
      ],
      "marketValue": 0.0,
      "currency": "EUR",
      "totalMarketValue": 0.0,
      "createdAt": "2026-03-07T14:22:00Z",
      "updatedAt": "2026-03-07T14:22:00Z"
    }
  }
}
```

***

## Update Item

```http theme={null}
PATCH /items/{itemId}
Content-Type: multipart/form-data
```

Update an existing inventory item. Supports adding new images and removing existing ones.

**itemId** `integer` *required*

ID of the item to update

**name** `string` *required*

Updated item name

**description** `string`

Updated description

**barcode** `string`

Updated barcode

**containerId** `integer` *required*

Container ID (can be changed to move item)

**assetTypeId** `integer` *required*

Asset type ID (can be changed to reclassify item)

**locationId** `integer`

Updated location ID

**quantity** `integer` *required*

Updated quantity

**minStock** `integer` *required*

Updated minimum stock threshold

**customFieldValues** `string` *required*

JSON-encoded custom field values

**imageIdsToDelete** `string` (default: \[])

JSON-encoded array of image IDs to delete

Example: `[12, 45, 67]`

**images** `file[]`

New images to upload (appended to existing images)

```json theme={null}
{
  "data": {
    "id": 123,
    "name": "iPad Air (Updated)",
    "quantity": 3,
    "images": [
      {
        "id": 46,
        "url": "https://storage.example.com/uploads/item-123-new.jpg",
        "order": 0
      }
    ],
    "updatedAt": "2026-03-07T15:10:00Z"
  }
}
```

***

## Delete Item

```http theme={null}
DELETE /items/{itemId}
```

Permanently delete an inventory item and all associated images.

**itemId** `integer` *required*

ID of the item to delete

```text theme={null}
204 No Content
```

***

## Clone Item

```http theme={null}
POST /containers/{containerId}/asset-types/{assetTypeId}/items/clone
Content-Type: application/json
```

Create a duplicate of an existing item with all custom fields and image references.

**containerId** `integer` *required*

Container ID of the item to clone

**assetTypeId** `integer` *required*

Asset type ID of the item to clone

**item** `object` *required*

Complete InventoryItem object to clone (from `toJson()`)

**properties**

**id** `integer`

Original item ID (will be replaced with new ID)

**name** `string` *required*

Item name

**customFieldValues** `object`

Custom field values to copy

**images** `array`

Image references to copy (IDs will be reset)

```json theme={null}
{
  "id": 124,
  "name": "iPad Air",
  "containerId": 5,
  "assetTypeId": 3,
  "customFieldValues": {
    "color": "Space Gray",
    "storage": "64GB"
  },
  "images": [
    {
      "id": 0,
      "url": "https://storage.example.com/uploads/item-123-0.jpg"
    }
  ]
}
```

***

## Batch Import Items

```http theme={null}
POST /containers/{containerId}/asset-types/{assetTypeId}/items/batch
Content-Type: application/json
```

Bulk create multiple inventory items in a single request. Useful for importing from spreadsheets or external systems.

**containerId** `integer` *required*

Container ID where items will be created

**assetTypeId** `integer` *required*

Asset type ID for all items

**items** `array` *required*

Array of item data objects to create

**item object**

**name** `string` *required*

Item name

**description** `string`

Item description

**barcode** `string`

Barcode/UPC

**quantity** `integer` (default: 1)

Quantity

**minStock** `integer` (default: 1)

Min stock threshold

**locationId** `integer`

Location ID

**customFieldValues** `object`

Custom field key-value pairs

```json theme={null}
{
  "items": [
    {
      "name": "iPhone 15 Pro #1",
      "quantity": 1,
      "customFieldValues": {
        "color": "Natural Titanium",
        "storage": "256GB"
      }
    },
    {
      "name": "iPhone 15 Pro #2",
      "quantity": 1,
      "customFieldValues": {
        "color": "Black Titanium",
        "storage": "512GB"
      }
    }
  ]
}
```

```text theme={null}
201 Created
```

***

## Get Item Price History

```http theme={null}
GET /items/{itemId}/price-history
```

Retrieve the historical market value data points for an item.

**itemId** `integer` *required*

ID of the item

```json theme={null}
[
  {
    "date": "2026-01-15T00:00:00Z",
    "value": 2499.99
  },
  {
    "date": "2026-02-01T00:00:00Z",
    "value": 2399.99
  },
  {
    "date": "2026-03-01T00:00:00Z",
    "value": 2299.99
  }
]
```

**date** `string`

ISO 8601 timestamp of the price point

**value** `number`

Market value at that date

***

## Sync Item with Market Data

```http theme={null}
POST /market/sync-item/{itemId}
```

Fetch current market value using the item's barcode/UPC from external pricing APIs.

**itemId** `integer` *required*

ID of the item to sync

```json theme={null}
{
  "data": {
    "id": 123,
    "name": "iPad Air",
    "barcode": "194253912736",
    "marketValue": 649.99,
    "currency": "EUR",
    "totalMarketValue": 649.99,
    "lastPriceUpdate": "2026-03-07T16:00:00Z"
  }
}
```

### Error Responses

```json theme={null}
{
  "error": "El ítem no tiene código de barras"
}
```

Common errors:

* `"El ítem no tiene código de barras"` - Item has no barcode set
* `"No se encontró información de mercado para este código"` - No market data found

***

## Get Total Market Value

```http theme={null}
GET /total-market-value
```

Calculate the total market value of all items across all containers.

```json theme={null}
{
  "totalMarketValue": 45678.90
}
```

**totalMarketValue** `number`

Sum of all items' totalMarketValue fields

***

## Error Handling

All endpoints return standard HTTP status codes:

* `200 OK` - Request successful
* `201 Created` - Resource created successfully
* `204 No Content` - Deletion successful
* `400 Bad Request` - Invalid parameters or malformed request
* `401 Unauthorized` - Authentication required
* `404 Not Found` - Resource not found
* `500 Internal Server Error` - Server error

Error responses include a message:

```json theme={null}
{
  "message": "Validation error description",
  "error": "Detailed error information"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.