Skip to main content

​
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. 
GET /admin/inventory-items

​
Query Parameters

​
fields
string
Comma-separated list of fields to include.
​
limit
number
default:"15"
Maximum number of inventory items to return.
​
offset
number
default:"0"
Number of inventory items to skip.
​
q
string
Search query for inventory item SKU or title.
​
sku
string
Filter by exact SKU.
​
location_id
string[]
Filter by stock location IDs.

​
Request

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

​
Response

{
  "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
}
​
inventory_items
InventoryItem[]
Array of inventory item objects.
​
count
number
Total number of inventory items matching the filters.
Source: packages/medusa/src/api/admin/inventory-items/route.ts:34

​
Create Inventory Item

Create a new inventory item. 
POST /admin/inventory-items

​
Request Body

​
sku
string
Stock keeping unit for the inventory item.
​
title
string
Title of the inventory item.
​
description
string
Description of the inventory item.
​
origin_country
string
Country of origin (two-letter ISO code).
​
hs_code
string
Harmonized System code for customs.
​
mid_code
string
Manufacturer Identification code.
​
material
string
Material composition.
​
weight
number
Weight in grams.
​
length
number
Length dimension.
​
height
number
Height dimension.
​
width
number
Width dimension.
​
requires_shipping
boolean
default:"true"
Whether the item requires shipping.
​
metadata
object
Custom metadata key-value pairs.

​
Request

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

{
  "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. 
GET /admin/inventory-items/{id}

​
Path Parameters

​
id
string
required
The inventory item’s ID.

​
Request

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

​
Response

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

​
Update Inventory Item

Update inventory item details. 
POST /admin/inventory-items/{id}

​
Path Parameters

​
id
string
required
The inventory item’s ID.

​
Request Body

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

​
Request

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. 
DELETE /admin/inventory-items/{id}

​
Path Parameters

​
id
string
required
The inventory item’s ID.

​
Request

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

​
Response

{
  "id": "inv_123",
  "object": "inventory-item",
  "deleted": true
}

​
Stock Levels

​
List Stock Levels

Retrieve stock levels for an inventory item across all locations. 
GET /admin/inventory-items/{id}/location-levels

​
Response

{
  "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
      }
    ]
  }
}
​
stocked_quantity
number
Total quantity in stock at the location.
​
reserved_quantity
number
Quantity reserved for pending orders.
​
incoming_quantity
number
Quantity expected to arrive.
​
available_quantity
number
Available quantity (stocked - reserved).

​
Update Stock Level

Update the stock quantity at a specific location. 
POST /admin/inventory-items/{id}/location-levels/{location_id}

​
Request Body

​
stocked_quantity
number
Set the stocked quantity.
​
incoming_quantity
number
Set the incoming quantity.

​
Request

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. 
POST /admin/inventory-items/{id}/location-levels

​
Request Body

​
location_id
string
required
The stock location ID.
​
stocked_quantity
number
default:"0"
Initial stock quantity.

​
Delete Stock Level

Remove an inventory item from a location. 
DELETE /admin/inventory-items/{id}/location-levels/{location_id}

​
Reservations

​
List Reservations

Retrieve all reservations for an inventory item. 
GET /admin/reservations?inventory_item_id={inventory_item_id}

​
Response

{
  "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. 
POST /admin/reservations

​
Request Body

​
inventory_item_id
string
required
The inventory item ID.
​
location_id
string
required
The stock location ID.
​
quantity
number
required
Quantity to reserve.
​
line_item_id
string
Associated order line item ID.
​
metadata
object
Custom metadata.

​
Delete Reservation

Remove an inventory reservation. 
DELETE /admin/reservations/{id}

​
Next Steps

Products

Manage product variants and inventory

Stock Locations

Learn about stock location management

Build docs developers (and LLMs) love

Get started for freeTalk to us