> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# Inventory

> Admin API endpoints for managing inventory items, stock levels, and reservations.

## Overview

The Inventory API provides endpoints for managing inventory items, tracking stock levels across locations, and handling inventory reservations.

**Base Path:** `/admin/inventory-items`

**Source:** `packages/medusa/src/api/admin/inventory-items/route.ts`

## List Inventory Items

Retrieve a list of inventory items with filtering and pagination.

```bash theme={null}
GET /admin/inventory-items
```

### Query Parameters

<ParamField query="fields" type="string">
  Comma-separated list of fields to include.
</ParamField>

<ParamField query="limit" type="number" default="15">
  Maximum number of inventory items to return.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of inventory items to skip.
</ParamField>

<ParamField query="q" type="string">
  Search query for inventory item SKU or title.
</ParamField>

<ParamField query="sku" type="string">
  Filter by exact SKU.
</ParamField>

<ParamField query="location_id" type="string[]">
  Filter by stock location IDs.
</ParamField>

### Request

```bash theme={null}
curl -X GET http://localhost:9000/admin/inventory-items \
  -H "Authorization: Bearer {token}" \
  -G \
  --data-urlencode "limit=50"
```

### Response

```json theme={null}
{
  "inventory_items": [
    {
      "id": "inv_123",
      "sku": "SHIRT-SM-BLK",
      "title": "Premium T-Shirt - Small - Black",
      "description": "Inventory for small black t-shirt",
      "origin_country": "US",
      "hs_code": "6109.10.00",
      "mid_code": null,
      "material": "Cotton",
      "weight": 200,
      "length": null,
      "height": null,
      "width": null,
      "requires_shipping": true,
      "metadata": {},
      "created_at": "2024-03-03T10:00:00.000Z",
      "updated_at": "2024-03-03T10:00:00.000Z"
    }
  ],
  "count": 450,
  "offset": 0,
  "limit": 50
}
```

<ResponseField name="inventory_items" type="InventoryItem[]">
  Array of inventory item objects.
</ResponseField>

<ResponseField name="count" type="number">
  Total number of inventory items matching the filters.
</ResponseField>

**Source:** `packages/medusa/src/api/admin/inventory-items/route.ts:34`

## Create Inventory Item

Create a new inventory item.

```bash theme={null}
POST /admin/inventory-items
```

### Request Body

<ParamField body="sku" type="string">
  Stock keeping unit for the inventory item.
</ParamField>

<ParamField body="title" type="string">
  Title of the inventory item.
</ParamField>

<ParamField body="description" type="string">
  Description of the inventory item.
</ParamField>

<ParamField body="origin_country" type="string">
  Country of origin (two-letter ISO code).
</ParamField>

<ParamField body="hs_code" type="string">
  Harmonized System code for customs.
</ParamField>

<ParamField body="mid_code" type="string">
  Manufacturer Identification code.
</ParamField>

<ParamField body="material" type="string">
  Material composition.
</ParamField>

<ParamField body="weight" type="number">
  Weight in grams.
</ParamField>

<ParamField body="length" type="number">
  Length dimension.
</ParamField>

<ParamField body="height" type="number">
  Height dimension.
</ParamField>

<ParamField body="width" type="number">
  Width dimension.
</ParamField>

<ParamField body="requires_shipping" type="boolean" default="true">
  Whether the item requires shipping.
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata key-value pairs.
</ParamField>

### Request

```bash theme={null}
curl -X POST http://localhost:9000/admin/inventory-items \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "SHIRT-MD-BLU",
    "title": "Premium T-Shirt - Medium - Blue",
    "weight": 210,
    "material": "Cotton",
    "origin_country": "US"
  }'
```

### Response

```json theme={null}
{
  "inventory_item": {
    "id": "inv_456",
    "sku": "SHIRT-MD-BLU",
    "title": "Premium T-Shirt - Medium - Blue",
    "weight": 210,
    "material": "Cotton",
    "origin_country": "US",
    "created_at": "2024-03-03T12:00:00.000Z"
  }
}
```

**Source:** `packages/medusa/src/api/admin/inventory-items/route.ts:14`

## Get Inventory Item

Retrieve a single inventory item by ID.

```bash theme={null}
GET /admin/inventory-items/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The inventory item's ID.
</ParamField>

### Request

```bash theme={null}
curl -X GET http://localhost:9000/admin/inventory-items/inv_123 \
  -H "Authorization: Bearer {token}"
```

### Response

```json theme={null}
{
  "inventory_item": {
    "id": "inv_123",
    "sku": "SHIRT-SM-BLK",
    "title": "Premium T-Shirt - Small - Black",
    "location_levels": [...]
  }
}
```

## Update Inventory Item

Update inventory item details.

```bash theme={null}
POST /admin/inventory-items/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The inventory item's ID.
</ParamField>

### Request Body

Accepts the same fields as Create Inventory Item, all optional.

### Request

```bash theme={null}
curl -X POST http://localhost:9000/admin/inventory-items/inv_123 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "weight": 220,
    "metadata": {
      "warehouse_section": "A-12"
    }
  }'
```

## Delete Inventory Item

Delete an inventory item.

```bash theme={null}
DELETE /admin/inventory-items/{id}
```

### Path Parameters

<ParamField path="id" type="string" required>
  The inventory item's ID.
</ParamField>

### Request

```bash theme={null}
curl -X DELETE http://localhost:9000/admin/inventory-items/inv_123 \
  -H "Authorization: Bearer {token}"
```

### Response

```json theme={null}
{
  "id": "inv_123",
  "object": "inventory-item",
  "deleted": true
}
```

## Stock Levels

### List Stock Levels

Retrieve stock levels for an inventory item across all locations.

```bash theme={null}
GET /admin/inventory-items/{id}/location-levels
```

### Response

```json theme={null}
{
  "inventory_item": {
    "id": "inv_123",
    "location_levels": [
      {
        "id": "level_123",
        "location_id": "sloc_warehouse1",
        "stocked_quantity": 100,
        "reserved_quantity": 10,
        "incoming_quantity": 50,
        "available_quantity": 90
      },
      {
        "id": "level_456",
        "location_id": "sloc_warehouse2",
        "stocked_quantity": 50,
        "reserved_quantity": 5,
        "incoming_quantity": 0,
        "available_quantity": 45
      }
    ]
  }
}
```

<ResponseField name="stocked_quantity" type="number">
  Total quantity in stock at the location.
</ResponseField>

<ResponseField name="reserved_quantity" type="number">
  Quantity reserved for pending orders.
</ResponseField>

<ResponseField name="incoming_quantity" type="number">
  Quantity expected to arrive.
</ResponseField>

<ResponseField name="available_quantity" type="number">
  Available quantity (stocked - reserved).
</ResponseField>

### Update Stock Level

Update the stock quantity at a specific location.

```bash theme={null}
POST /admin/inventory-items/{id}/location-levels/{location_id}
```

### Request Body

<ParamField body="stocked_quantity" type="number">
  Set the stocked quantity.
</ParamField>

<ParamField body="incoming_quantity" type="number">
  Set the incoming quantity.
</ParamField>

### Request

```bash theme={null}
curl -X POST http://localhost:9000/admin/inventory-items/inv_123/location-levels/sloc_warehouse1 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "stocked_quantity": 150
  }'
```

### Create Stock Level

Add an inventory item to a new location.

```bash theme={null}
POST /admin/inventory-items/{id}/location-levels
```

### Request Body

<ParamField body="location_id" type="string" required>
  The stock location ID.
</ParamField>

<ParamField body="stocked_quantity" type="number" default="0">
  Initial stock quantity.
</ParamField>

### Delete Stock Level

Remove an inventory item from a location.

```bash theme={null}
DELETE /admin/inventory-items/{id}/location-levels/{location_id}
```

## Reservations

### List Reservations

Retrieve all reservations for an inventory item.

```bash theme={null}
GET /admin/reservations?inventory_item_id={inventory_item_id}
```

### Response

```json theme={null}
{
  "reservations": [
    {
      "id": "res_123",
      "inventory_item_id": "inv_123",
      "location_id": "sloc_warehouse1",
      "quantity": 2,
      "line_item_id": "item_456",
      "metadata": {},
      "created_at": "2024-03-03T10:00:00.000Z"
    }
  ]
}
```

**Source:** `packages/medusa/src/api/admin/reservations/route.ts`

### Create Reservation

Manually create an inventory reservation.

```bash theme={null}
POST /admin/reservations
```

### Request Body

<ParamField body="inventory_item_id" type="string" required>
  The inventory item ID.
</ParamField>

<ParamField body="location_id" type="string" required>
  The stock location ID.
</ParamField>

<ParamField body="quantity" type="number" required>
  Quantity to reserve.
</ParamField>

<ParamField body="line_item_id" type="string">
  Associated order line item ID.
</ParamField>

<ParamField body="metadata" type="object">
  Custom metadata.
</ParamField>

### Delete Reservation

Remove an inventory reservation.

```bash theme={null}
DELETE /admin/reservations/{id}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Products" icon="box" href="/api/admin/products">
    Manage product variants and inventory
  </Card>

  <Card title="Stock Locations" icon="warehouse" href="/modules/stock-location">
    Learn about stock location management
  </Card>
</CardGroup>