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.

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