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. 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 to learn how to obtain one.
Seller ID: Use the GET /sellers endpoint to find it.
Warehouse ID: Use the GET /warehouses endpoint to list available warehouses.
Completed inbound: You should have sent inventory and the inbound status should be COMPLETED. See the Send Inventory guide if you have not sent inventory yet.
Articles created: Products must exist as articles. See the Create Products guide if you have not created articles yet.

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.

Check stock levels by warehouse

To check stock levels for all items in a specific warehouse, use the GET /items/{warehouseId}/{sellerId} endpoint. 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.

Request
Response

Use this request to list all items and their stock levels in a specific warehouse.

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>"

A successful request returns a 200 OK status code with an array of ItemInfo objects:

[
  {
    "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

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:

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:

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. Use the itemId from the item list response.

Request
Response

Use this request to retrieve detailed information for a single item.

curl -X GET "${BASE_URL}/items/<YOUR_ITEM_ID>" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

A successful request returns a 200 OK status code with an ItemInfo object containing complete item details:

{
  "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": []
}

View item movements and history

To view the movement history for a specific item, use the GET /items/{itemId}/movements endpoint. This shows all movements (inbound, outbound, adjustments) for the item. Use the itemId from the item details.

Request
Response

Use this request to retrieve movement history for a specific item.

curl -X GET "${BASE_URL}/items/<YOUR_ITEM_ID>/movements" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

A successful request returns a 200 OK status code with an ItemMovements object containing movement history:

{
  "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.

Filter movements by date range

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

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. 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.

Request
Response

Use this request to retrieve movement history for all items in a warehouse:

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>"

A successful request returns a 200 OK status code with an array of ItemHistorySummary objects:

[
  {
    "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.

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. This operation syncs the item’s inventory data with the warehouse system.

Request
Response

Use this request to refresh inventory data for a specific item.

curl -X POST "${BASE_URL}/items/<YOUR_ITEM_ID>/refresh" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

A successful request returns a 200 OK status code with the updated ItemInfo object:

{
  "itemId": <ITEM_ID>,
  "quantity": <UPDATED_QUANTITY>,
  "inventory": <UPDATED_INVENTORY_QUANTITY>,
  "inbound": <UPDATED_INBOUND_QUANTITY>,
  "reserved": <UPDATED_RESERVED_QUANTITY>
}

Refresh all seller items

To refresh inventory for all items belonging to a seller, use the POST /items/seller/{sellerId}/refresh endpoint. This operation syncs all items for your seller account with the warehouse system.

Request
Response

Use this request to refresh inventory data for all items for a seller.

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

A successful request returns a 200 OK status code with no response body. The refresh operation is processed asynchronously.

Where to go next

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

Create a Fulfillment Order

Create orders to fulfill customer purchases. Use inventory levels to ensure products are available before creating orders.

Track an Order

Monitor order status and retrieve tracking information when Quivo ships orders from the warehouse.

Introduction

Quickstart

Quivo Flows

Webhooks

Prerequisites

Check stock levels by warehouse

Filter and search items

Get item details

View item movements and history

Filter movements by date range

View item history by warehouse

Refresh inventory data

Refresh a specific item

Refresh all seller items

Where to go next

Create a Fulfillment Order

Track an Order

Introduction

Quickstart

Quivo Flows

Webhooks

​Prerequisites

​Check stock levels by warehouse

​Filter and search items

​Get item details

​View item movements and history

​Filter movements by date range

​View item history by warehouse

​Refresh inventory data

​Refresh a specific item

​Refresh all seller items

​Where to go next

Create a Fulfillment Order

Track an Order

Prerequisites

Check stock levels by warehouse

Filter and search items

Get item details

View item movements and history

Filter movements by date range

View item history by warehouse

Refresh inventory data

Refresh a specific item

Refresh all seller items

Where to go next