> ## 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 Module

> Learn about the Inventory Module and how to manage inventory items, stock levels, and reservations in Medusa.

## Overview

The Inventory Module manages inventory tracking across multiple stock locations. It handles inventory items, stock levels per location, and inventory reservations for orders and carts.

**Key Features:**

* Inventory item management
* Multi-location stock levels
* Inventory reservations
* Available quantity calculations
* Backorder support
* Stock adjustments and tracking

## When to Use

Use the Inventory Module when you need to:

* Track inventory across multiple warehouses
* Reserve inventory for orders and carts
* Check product availability
* Manage stock levels per location
* Support backorders
* Adjust inventory quantities
* Track incoming and stocked quantities

## Data Models

### InventoryItem

Represents a trackable inventory item (usually linked to product variants).

<ResponseField name="id" type="string" required>
  Unique inventory item identifier
</ResponseField>

<ResponseField name="sku" type="string">
  Stock keeping unit identifier
</ResponseField>

<ResponseField name="origin_country" type="string">
  Country of origin (two-letter ISO code)
</ResponseField>

<ResponseField name="hs_code" type="string">
  Harmonized System code for customs
</ResponseField>

<ResponseField name="mid_code" type="string">
  Manufacturer item number
</ResponseField>

<ResponseField name="material" type="string">
  Item material composition
</ResponseField>

<ResponseField name="weight" type="number">
  Item weight
</ResponseField>

<ResponseField name="length" type="number">
  Item length
</ResponseField>

<ResponseField name="height" type="number">
  Item height
</ResponseField>

<ResponseField name="width" type="number">
  Item width
</ResponseField>

<ResponseField name="requires_shipping" type="boolean">
  Whether item requires shipping
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional custom data
</ResponseField>

### InventoryLevel

Tracks stock quantity for an inventory item at a specific location.

<ResponseField name="id" type="string" required>
  Unique inventory level identifier
</ResponseField>

<ResponseField name="inventory_item_id" type="string" required>
  ID of the inventory item
</ResponseField>

<ResponseField name="location_id" type="string" required>
  ID of the stock location
</ResponseField>

<ResponseField name="stocked_quantity" type="BigNumber" required>
  Quantity physically stocked at location
</ResponseField>

<ResponseField name="reserved_quantity" type="BigNumber" required>
  Quantity reserved (calculated from reservations)
</ResponseField>

<ResponseField name="incoming_quantity" type="BigNumber" required>
  Quantity expected to arrive
</ResponseField>

<ResponseField name="available_quantity" type="BigNumber">
  Available quantity (calculated: stocked - reserved)
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional custom data
</ResponseField>

### ReservationItem

Reserves inventory for orders, carts, or other purposes.

<ResponseField name="id" type="string" required>
  Unique reservation identifier
</ResponseField>

<ResponseField name="inventory_item_id" type="string" required>
  ID of the inventory item
</ResponseField>

<ResponseField name="location_id" type="string" required>
  ID of the stock location
</ResponseField>

<ResponseField name="quantity" type="BigNumber" required>
  Reserved quantity
</ResponseField>

<ResponseField name="line_item_id" type="string">
  ID of the associated line item
</ResponseField>

<ResponseField name="description" type="string">
  Reservation description or reason
</ResponseField>

<ResponseField name="created_by" type="string">
  User ID who created the reservation
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional custom data
</ResponseField>

## Service Interface

The Inventory Module service is available at `@medusajs/medusa/inventory`.

### Create Inventory Item

Create a new inventory item.

<CodeGroup>
  ```typescript Example theme={null}
  import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
  import { IInventoryService } from "@medusajs/framework/types"
  import { Modules } from "@medusajs/framework/utils"

  export async function POST(
    req: MedusaRequest,
    res: MedusaResponse
  ) {
    const inventoryModuleService: IInventoryService = req.scope.resolve(
      Modules.INVENTORY
    )

    const inventoryItem = await inventoryModuleService.createInventoryItems({
      sku: "TSHIRT-M-BLACK",
      requires_shipping: true,
      weight: 200,
    })

    res.json({ inventory_item: inventoryItem })
  }
  ```
</CodeGroup>

<ParamField path="data" type="CreateInventoryItemDTO | CreateInventoryItemDTO[]" required>
  Inventory item data

  <ParamField path="sku" type="string">
    Stock keeping unit
  </ParamField>

  <ParamField path="requires_shipping" type="boolean">
    Whether item requires shipping
  </ParamField>

  <ParamField path="weight" type="number">
    Item weight
  </ParamField>

  <ParamField path="length" type="number">
    Item length
  </ParamField>

  <ParamField path="height" type="number">
    Item height
  </ParamField>

  <ParamField path="width" type="number">
    Item width
  </ParamField>
</ParamField>

<ResponseField name="inventoryItem" type="InventoryItemDTO | InventoryItemDTO[]">
  The created inventory item(s)
</ResponseField>

### Create Inventory Level

Set stock quantity at a location.

<CodeGroup>
  ```typescript Example theme={null}
  const inventoryLevel = await inventoryModuleService.createInventoryLevels({
    inventory_item_id: "iitem_123",
    location_id: "sloc_warehouse",
    stocked_quantity: 100,
    incoming_quantity: 50,
  })
  ```
</CodeGroup>

<ParamField path="data" type="CreateInventoryLevelDTO | CreateInventoryLevelDTO[]" required>
  Inventory level data

  <ParamField path="inventory_item_id" type="string" required>
    ID of the inventory item
  </ParamField>

  <ParamField path="location_id" type="string" required>
    ID of the stock location
  </ParamField>

  <ParamField path="stocked_quantity" type="number" required>
    Quantity in stock
  </ParamField>

  <ParamField path="incoming_quantity" type="number">
    Quantity expected to arrive
  </ParamField>
</ParamField>

### Update Inventory Level

Adjust stock quantities.

<CodeGroup>
  ```typescript Example theme={null}
  const inventoryLevel = await inventoryModuleService.updateInventoryLevels({
    inventory_item_id: "iitem_123",
    location_id: "sloc_warehouse",
    stocked_quantity: 150, // New total quantity
  })
  ```

  ```typescript Adjust Quantity theme={null}
  const inventoryLevel = await inventoryModuleService.adjustInventory(
    "iitem_123",
    "sloc_warehouse",
    10 // Add 10 to current quantity
  )
  ```
</CodeGroup>

<ParamField path="data" type="UpdateInventoryLevelDTO" required>
  Update data

  <ParamField path="inventory_item_id" type="string" required>
    ID of the inventory item
  </ParamField>

  <ParamField path="location_id" type="string" required>
    ID of the stock location
  </ParamField>

  <ParamField path="stocked_quantity" type="number">
    New stocked quantity
  </ParamField>

  <ParamField path="incoming_quantity" type="number">
    New incoming quantity
  </ParamField>
</ParamField>

### Retrieve Inventory Level

Get inventory level for item at location.

<CodeGroup>
  ```typescript Example theme={null}
  const inventoryLevel = await inventoryModuleService.retrieveInventoryLevel(
    "iitem_123",
    "sloc_warehouse"
  )

  console.log(inventoryLevel.available_quantity)
  ```
</CodeGroup>

<ParamField path="inventoryItemId" type="string" required>
  ID of the inventory item
</ParamField>

<ParamField path="locationId" type="string" required>
  ID of the stock location
</ParamField>

<ResponseField name="inventoryLevel" type="InventoryLevelDTO">
  The inventory level with available quantity
</ResponseField>

### Create Reservation

Reserve inventory for an order or cart.

<CodeGroup>
  ```typescript Example theme={null}
  const reservation = await inventoryModuleService.createReservationItems({
    inventory_item_id: "iitem_123",
    location_id: "sloc_warehouse",
    quantity: 2,
    line_item_id: "item_456",
    description: "Order reservation",
  })
  ```
</CodeGroup>

<ParamField path="data" type="CreateReservationItemDTO | CreateReservationItemDTO[]" required>
  Reservation data

  <ParamField path="inventory_item_id" type="string" required>
    ID of the inventory item
  </ParamField>

  <ParamField path="location_id" type="string" required>
    ID of the stock location
  </ParamField>

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

  <ParamField path="line_item_id" type="string">
    ID of the line item
  </ParamField>

  <ParamField path="description" type="string">
    Reservation description
  </ParamField>
</ParamField>

<ResponseField name="reservation" type="ReservationItemDTO | ReservationItemDTO[]">
  The created reservation(s)
</ResponseField>

### Update Reservation

Modify reservation quantity.

<CodeGroup>
  ```typescript Example theme={null}
  const reservation = await inventoryModuleService.updateReservationItems(
    "res_123",
    {
      quantity: 3, // Update to 3 items
    }
  )
  ```
</CodeGroup>

### Delete Reservation

Release reserved inventory.

<CodeGroup>
  ```typescript Example theme={null}
  await inventoryModuleService.deleteReservationItems(["res_123", "res_456"])
  ```
</CodeGroup>

### Confirm Inventory

Check if sufficient inventory is available.

<CodeGroup>
  ```typescript Example theme={null}
  const isAvailable = await inventoryModuleService.confirmInventory(
    "iitem_123",
    ["sloc_warehouse"],
    5 // Quantity needed
  )

  if (!isAvailable) {
    throw new Error("Insufficient inventory")
  }
  ```
</CodeGroup>

<ParamField path="inventoryItemId" type="string" required>
  ID of the inventory item
</ParamField>

<ParamField path="locationIds" type="string[]" required>
  IDs of stock locations to check
</ParamField>

<ParamField path="quantity" type="number" required>
  Required quantity
</ParamField>

<ResponseField name="isAvailable" type="boolean">
  Whether sufficient inventory is available
</ResponseField>

### Retrieve Available Quantity

Get available quantity across locations.

<CodeGroup>
  ```typescript Example theme={null}
  const availableQuantity = await inventoryModuleService.retrieveAvailableQuantity(
    "iitem_123",
    ["sloc_warehouse", "sloc_store"]
  )
  ```
</CodeGroup>

### Retrieve Stocked Quantity

Get total stocked quantity across locations.

<CodeGroup>
  ```typescript Example theme={null}
  const stockedQuantity = await inventoryModuleService.retrieveStockedQuantity(
    "iitem_123",
    ["sloc_warehouse", "sloc_store"]
  )
  ```
</CodeGroup>

### Retrieve Reserved Quantity

Get total reserved quantity.

<CodeGroup>
  ```typescript Example theme={null}
  const reservedQuantity = await inventoryModuleService.retrieveReservedQuantity(
    "iitem_123",
    ["sloc_warehouse"]
  )
  ```
</CodeGroup>

## Integration Examples

### With Product Module

Create inventory for product variants.

<CodeGroup>
  ```typescript Example theme={null}
  import { Modules } from "@medusajs/framework/utils"

  const productModule = container.resolve(Modules.PRODUCT)
  const inventoryModule = container.resolve(Modules.INVENTORY)

  // Create product with variants
  const product = await productModule.createProducts({
    title: "T-Shirt",
    variants: [
      { title: "Small", sku: "TSHIRT-S" },
      { title: "Medium", sku: "TSHIRT-M" },
    ],
  })

  // Create inventory items for variants
  for (const variant of product.variants) {
    const inventoryItem = await inventoryModule.createInventoryItems({
      sku: variant.sku,
    })
    
    // Link variant to inventory (via workflows)
    
    // Set stock level
    await inventoryModule.createInventoryLevels({
      inventory_item_id: inventoryItem.id,
      location_id: "sloc_warehouse",
      stocked_quantity: 100,
    })
  }
  ```
</CodeGroup>

### With Cart Module

Check availability and reserve inventory.

<CodeGroup>
  ```typescript Example theme={null}
  import { Modules } from "@medusajs/framework/utils"

  const cartModule = container.resolve(Modules.CART)
  const inventoryModule = container.resolve(Modules.INVENTORY)

  // Get cart with items
  const cart = await cartModule.retrieveCart("cart_123", {
    relations: ["items"],
  })

  // Check availability for each item
  for (const item of cart.items) {
    const isAvailable = await inventoryModule.confirmInventory(
      item.inventory_item_id,
      ["sloc_warehouse"],
      item.quantity
    )
    
    if (!isAvailable) {
      throw new Error(`Item ${item.title} is out of stock`)
    }
    
    // Reserve inventory
    await inventoryModule.createReservationItems({
      inventory_item_id: item.inventory_item_id,
      location_id: "sloc_warehouse",
      quantity: item.quantity,
      line_item_id: item.id,
      description: "Cart reservation",
    })
  }
  ```
</CodeGroup>

### With Order Module

Adjust inventory on order completion.

<CodeGroup>
  ```typescript Example theme={null}
  import { Modules } from "@medusajs/framework/utils"

  const orderModule = container.resolve(Modules.ORDER)
  const inventoryModule = container.resolve(Modules.INVENTORY)

  // Order completed - adjust inventory
  const order = await orderModule.retrieveOrder("order_123", {
    relations: ["items"],
  })

  // Convert reservations to actual deductions
  for (const item of order.items) {
    // Delete reservation
    await inventoryModule.deleteReservationItems([item.reservation_id])
    
    // Adjust stocked quantity
    await inventoryModule.adjustInventory(
      item.inventory_item_id,
      "sloc_warehouse",
      -item.quantity // Subtract from stock
    )
  }
  ```
</CodeGroup>

### With Stock Location Module

Manage inventory across multiple locations.

<CodeGroup>
  ```typescript Example theme={null}
  import { Modules } from "@medusajs/framework/utils"

  const stockLocationModule = container.resolve(Modules.STOCK_LOCATION)
  const inventoryModule = container.resolve(Modules.INVENTORY)

  // Get all stock locations
  const locations = await stockLocationModule.listStockLocations()

  // Set inventory levels at each location
  for (const location of locations) {
    await inventoryModule.createInventoryLevels({
      inventory_item_id: "iitem_123",
      location_id: location.id,
      stocked_quantity: 50,
    })
  }

  // Check total available quantity across all locations
  const totalAvailable = await inventoryModule.retrieveAvailableQuantity(
    "iitem_123",
    locations.map(l => l.id)
  )
  ```
</CodeGroup>

### With Fulfillment Module

Reserve inventory for fulfillment.

<CodeGroup>
  ```typescript Example theme={null}
  import { Modules } from "@medusajs/framework/utils"

  const fulfillmentModule = container.resolve(Modules.FULFILLMENT)
  const inventoryModule = container.resolve(Modules.INVENTORY)

  // Create fulfillment
  const fulfillment = await fulfillmentModule.createFulfillment({
    location_id: "sloc_warehouse",
    provider_id: "manual",
    items: [
      { line_item_id: "item_123", quantity: 2 },
    ],
  })

  // Deduct from inventory
  await inventoryModule.adjustInventory(
    "iitem_123",
    "sloc_warehouse",
    -2
  )
  ```
</CodeGroup>

## Best Practices

1. **Reserved Quantity**: The `reserved_quantity` field is calculated automatically from reservation items. Never update it directly - always create/delete reservations.

2. **Inventory Adjustments**: Use `adjustInventory` for relative changes (add/subtract), `updateInventoryLevels` for absolute values.

3. **Reservation Lifecycle**:
   * Create reservation when adding to cart
   * Update reservation when cart quantity changes
   * Delete reservation when:
     * Cart is completed (order created)
     * Cart item is removed
     * Cart expires

4. **Multi-Location**: When checking availability, always specify which locations to check. This is crucial for multi-warehouse scenarios.

5. **Backorders**: Set appropriate thresholds for when to allow backorders. Check `available_quantity` and compare with `incoming_quantity`.

6. **Bulk Operations**: Use array input for bulk operations to improve performance when creating multiple inventory items or levels.

## Related Modules

* [Product Module](/modules/product) - Link inventory to product variants
* [Stock Location Module](/modules/stock-location) - Manage warehouse locations
* [Cart Module](/modules/cart) - Reserve inventory for carts
* [Order Module](/modules/order) - Adjust inventory on orders
* [Fulfillment Module](/modules/fulfillment) - Reserve for fulfillments