> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.quivo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitor Inventory

This guide shows you how to check stock levels, view inventory by warehouse, and track item movements using the Items API. After you send inventory to a Quivo warehouse and the inbound completes, your products are available as items in the warehouse.

Understanding the distinction between articles and items is important:

* **Article:** A product definition in your catalog created using the Articles API
* **Item:** A physical unit of inventory stored in a warehouse, created from articles after you send inventory to a warehouse and the inbound completes.

An article can have many items across different warehouses, with each item representing physical stock at a specific warehouse location. For detailed definitions of these terms, see the [Logistics Glossary](/docs/introduction/logistics-glossary).

This guide teaches you how to check current stock levels, view item history, and refresh inventory data when needed.

## Prerequisites

Before you start, make sure you have:

* **Session token:** A valid session token. See the [Authentication guide](/api-reference/authentication) to learn how to obtain one.
* **Seller ID:** Use the [`GET /sellers endpoint`](/api-reference/#tag/sellers) to find it.
* **Warehouse ID:** Use the [`GET /warehouses endpoint`](/api-reference/#tag/warehouses) to list available warehouses.
* **Completed inbound:** You should have sent inventory and the inbound status should be `COMPLETED`. See the [Send Inventory guide](/docs/quickstart/send-inventory) if you have not sent inventory yet.
* **Articles created:** Products must exist as articles. See the [Create Products guide](/docs/quivo-guides/create-products) if you have not created articles yet.

<Note>
  All API examples in this guide use `${BASE_URL}` as a placeholder. Replace it with the correct base URL configured for the correct environment. For more information see [Environments page](/api-reference/environments).
</Note>

## Check stock levels by warehouse

To check stock levels for all items in a specific warehouse, use the [`GET /items/{warehouseId}/{sellerId} endpoint`](/api-reference/#tag/items). This returns a list of all items in the warehouse with their current inventory levels. Replace the placeholders with your actual warehouse ID and seller ID.

<Tabs>
  <Tab title="Request">
    Use this request to list all items and their stock levels in a specific warehouse.

    ```bash theme={null}
    curl -X GET "${BASE_URL}/items/<YOUR_WAREHOUSE_ID>/<YOUR_SELLER_ID>" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an array of `ItemInfo` objects:

    ```json theme={null}
    [
      {
        "itemId": <ITEM_ID>,
        "articleId": <ARTICLE_ID>,
        "sku": "<YOUR_SKU>",
        "sellerSku": "<YOUR_SKU>",
        "warehouseSku": "<WAREHOUSE_SKU>",
        "name": "<PRODUCT_NAME>",
        "quantity": <AVAILABLE_QUANTITY>,
        "inventory": <INVENTORY_QUANTITY>,
        "inbound": <INBOUND_QUANTITY>,
        "reserved": <RESERVED_QUANTITY>,
        "warehouseId": <WAREHOUSE_ID>,
        "articleName": {
          "value": "<PRODUCT_NAME>",
          "language": "EN"
        },
        "articleType": "PRODUCT"
      }
    ]
    ```

    The response includes key inventory fields:

    * `quantity`: Current available quantity ready for fulfillment
    * `inventory`: Total inventory quantity in the warehouse
    * `inbound`: Quantity that Quivo is currently processing from inbound shipments
    * `reserved`: Quantity reserved for pending orders
  </Tab>
</Tabs>

### Filter and search items

You can use query parameters to filter and search items:

* **`query`**: Search query string to filter results across multiple fields, for example SKU or name
* **`sort`**: Sort criteria, for example `quantity:desc` to sort by quantity descending
* **`page`**: Page number for pagination
* **`pageSize`**: Number of items per page

**Search by SKU:**

```bash theme={null}
curl -X GET "${BASE_URL}/items/<YOUR_WAREHOUSE_ID>/<YOUR_SELLER_ID>?query=<YOUR_SKU>" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"
```

**Sort by quantity:**

```bash theme={null}
curl -X GET "${BASE_URL}/items/<YOUR_WAREHOUSE_ID>/<YOUR_SELLER_ID>?sort=quantity:desc" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"
```

## Get item details

To get detailed information about a specific item, use the [`GET /items/{itemId} endpoint`](/api-reference/#tag/items). Use the `itemId` from the item list response.

<Tabs>
  <Tab title="Request">
    Use this request to retrieve detailed information for a single item.

    ```bash theme={null}
    curl -X GET "${BASE_URL}/items/<YOUR_ITEM_ID>" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an `ItemInfo` object containing complete item details:

    ```json theme={null}
    {
      "itemId": <ITEM_ID>,
      "articleId": <ARTICLE_ID>,
      "sku": "<YOUR_SKU>",
      "sellerSku": "<YOUR_SKU>",
      "warehouseSku": "<WAREHOUSE_SKU>",
      "name": "<PRODUCT_NAME>",
      "quantity": <AVAILABLE_QUANTITY>,
      "inventory": <INVENTORY_QUANTITY>,
      "inbound": <INBOUND_QUANTITY>,
      "reserved": <RESERVED_QUANTITY>,
      "warehouseId": <WAREHOUSE_ID>,
      "barcode": "<BARCODE>",
      "countryOfOrigin": "<COUNTRY_CODE>",
      "weight": <WEIGHT_VALUE>,
      "articleName": {
        "value": "<PRODUCT_NAME>",
        "language": "EN"
      },
      "articleType": "PRODUCT",
      "itemInventories": []
    }
    ```
  </Tab>
</Tabs>

## View item movements and history

To view the movement history for a specific item, use the [`GET /items/{itemId}/movements endpoint`](/api-reference/#tag/items). This shows all movements (inbound, outbound, adjustments) for the item. Use the `itemId` from the item details.

<Tabs>
  <Tab title="Request">
    Use this request to retrieve movement history for a specific item.

    ```bash theme={null}
    curl -X GET "${BASE_URL}/items/<YOUR_ITEM_ID>/movements" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an `ItemMovements` object containing movement history:

    ```json theme={null}
    {
      "warehouseName": "<WAREHOUSE_NAME>",
      "itemMovements": [
        {
          "movementDate": "<YYYY-MM-DD>",
          "warehouseIdentifier": "<WAREHOUSE_IDENTIFIER>",
          "reference": "<REFERENCE_ID>",
          "adjustmentQuantity": <ADJUSTMENT_QUANTITY>
        }
      ]
    }
    ```

    The movement history shows inventory changes over time. Dates use the ISO 8601 format YYYY-MM-DD, and timestamps use YYYY-MM-DDTHH:mm:ssZ in Coordinated Universal Time UTC.
  </Tab>
</Tabs>

### Filter movements by date range

You can filter movements by date range using the `movementFrom` and `movementTo` query parameters:

```bash theme={null}
curl -X GET "${BASE_URL}/items/<YOUR_ITEM_ID>/movements?movementFrom=2025-01-01T00:00:00Z&movementTo=2025-01-31T23:59:59Z" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"
```

## View item history by warehouse

To view item history for all items in a warehouse, use the [`GET /items/itemHistories/{warehouseId}/{sellerId} endpoint`](/api-reference/#tag/items). This provides a comprehensive history of all item movements in the warehouse. You can use query parameters like `query` and `sort` to filter and sort the results.

<Tabs>
  <Tab title="Request">
    Use this request to retrieve movement history for all items in a warehouse:

    ```bash theme={null}
    curl -X GET "${BASE_URL}/items/itemHistories/<YOUR_WAREHOUSE_ID>/<YOUR_SELLER_ID>" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an array of `ItemHistorySummary` objects:

    ```json theme={null}
    [
      {
        "warehouseId": <WAREHOUSE_ID>,
        "sellerId": <SELLER_ID>,
        "itemId": <ITEM_ID>,
        "warehouseSku": "<WAREHOUSE_SKU>",
        "sellerSku": "<SELLER_SKU>",
        "name": "<PRODUCT_NAME>",
        "barcode": "<BARCODE>",
        "inventory": <INVENTORY_QUANTITY>,
        "reserved": <RESERVED_QUANTITY>,
        "eventDate": "<YYYY-MM-DDTHH:mm:ssZ>",
        "itemHistoryInventories": [
          {
            "quantity": <QUANTITY>,
            "lot": "<LOT_NUMBER>",
            "expiration": "<YYYY-MM-DDTHH:mm:ssZ>",
            "locationBlocked": false
          }
        ]
      }
    ]
    ```

    Each object in the array represents an item history entry with inventory details and movement information.
  </Tab>
</Tabs>

## Refresh inventory data

If you notice discrepancies between your records and the warehouse inventory, you can trigger a refresh operation to sync inventory data with the warehouse system.

### Refresh a specific item

To refresh a specific item, use the [`POST /items/{itemId}/refresh endpoint`](/api-reference/#tag/items). This operation syncs the item's inventory data with the warehouse system.

<Tabs>
  <Tab title="Request">
    Use this request to refresh inventory data for a specific item.

    ```bash theme={null}
    curl -X POST "${BASE_URL}/items/<YOUR_ITEM_ID>/refresh" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with the updated `ItemInfo` object:

    ```json theme={null}
    {
      "itemId": <ITEM_ID>,
      "quantity": <UPDATED_QUANTITY>,
      "inventory": <UPDATED_INVENTORY_QUANTITY>,
      "inbound": <UPDATED_INBOUND_QUANTITY>,
      "reserved": <UPDATED_RESERVED_QUANTITY>
    }
    ```
  </Tab>
</Tabs>

### Refresh all seller items

To refresh inventory for all items belonging to a seller, use the [`POST /items/seller/{sellerId}/refresh endpoint`](/api-reference/#tag/items). This operation syncs all items for your seller account with the warehouse system.

<Tabs>
  <Tab title="Request">
    Use this request to refresh inventory data for all items for a seller.

    ```bash theme={null}
    curl -X POST "${BASE_URL}/items/seller/<YOUR_SELLER_ID>/refresh" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with no response body. The refresh operation is processed asynchronously.
  </Tab>
</Tabs>

## Where to go next

Now that you can monitor inventory, continue with these guides:

<CardGroup cols={2}>
  <Card title="Create a Fulfillment Order" icon="shopping-cart" href="/docs/quickstart/create-order">
    Create orders to fulfill customer purchases. Use inventory levels to ensure products are available before creating orders.
  </Card>

  <Card title="Track an Order" icon="location-dot" href="/docs/quickstart/track-order">
    Monitor order status and retrieve tracking information when Quivo ships orders from the warehouse.
  </Card>
</CardGroup>