Support for Adjusting incoming_quantity in Inventory Module

[lorenzo-polaris]

Problem Statement

Currently, the Inventory Module's adjustInventory method only supports adjusting the stocked_quantity field. The key advantage of this method is that it performs the read and update operations atomically within a transaction, preventing race conditions when multiple processes attempt to adjust inventory simultaneously.

However, the incoming_quantity field lacks this critical capability. While incoming_quantity can be set directly via createInventoryLevels and updateInventoryLevels, there is no way to atomically adjust (increment/decrement) the incoming quantity. Developers must:

1. Fetch the current inventory level
2. Read the current incoming_quantity value
3. Calculate the new value
4. Call updateInventoryLevels with the new value

This multi-step process introduces a race condition window between the read and write operations. In high-concurrency scenarios (e.g., multiple purchase orders being processed simultaneously, or concurrent inventory transfers), this can lead to lost updates, incorrect inventory counts, and data inconsistency.

Proposed Solution

Type Definition

// packages/core/types/src/inventory/mutations/inventory-level.ts
type BulkAdjustInventoryLevelInput = {
  inventory_item_id: string
  location_id: string
  adjustment?: BigNumberInput          // For stocked_quantity (optional)
  incoming_adjustment?: BigNumberInput // For incoming_quantity (optional, NEW)
}

Service Implementation (Pseudo-code)

Note: This is just a pseudo implementation to illustrate the concept. If the Medusa team approves this proposal, I will implement a production-ready version with proper error handling, validation, tests, and documentation.

// packages/modules/inventory/src/services/inventory-module.ts
async adjustInventory_(
  inventoryItemId: string,
  locationId: string,
  adjustment: BigNumberInput | undefined,
  incomingAdjustment: BigNumberInput | undefined,
  @MedusaContext() context: Context = {}
): Promise<InferEntityType<typeof InventoryLevel>> {
  const [inventoryLevel] = await this.inventoryLevelService_.list(
    { inventory_item_id: inventoryItemId, location_id: locationId },
    {},
    context
  )
  
  if (!inventoryLevel) {
    throw new MedusaError(
      MedusaError.Types.NOT_FOUND,
      `Inventory level for item ${inventoryItemId} and location ${locationId} not found`
    )
  }
  
  const result = await this.inventoryLevelService_.update(
    {
      id: inventoryLevel.id,
      ...(adjustment && {
        stocked_quantity: MathBN.add(
          inventoryLevel.stocked_quantity,
          adjustment
        )
      }),
      ...(incomingAdjustment && {
        incoming_quantity: MathBN.add(
          inventoryLevel.incoming_quantity,
          incomingAdjustment
        )
      }),
    },
    context
  )
  
  return result
}

Usage Examples

// Adjust only stocked quantity (existing behavior)
await adjustInventory({
  inventory_item_id: "iitem_123",
  location_id: "sloc_123",
  adjustment: 100
})

// Adjust only incoming quantity (NEW)
await adjustInventory({
  inventory_item_id: "iitem_123",
  location_id: "sloc_123",
  incoming_adjustment: 50
})

// Adjust both atomically (NEW - most powerful)
await adjustInventory({
  inventory_item_id: "iitem_123",
  location_id: "sloc_123",
  adjustment: 100,           // Add to stock
  incoming_adjustment: -100  // Remove from incoming
})

Would love to hear the Medusa team's thoughts on this proposal! If approved, I'm ready to implement a production-ready version with comprehensive tests and documentation.