Inventory & Warehouse Management

Overview

• What you’ll learn:
  • How iDempiere organizes warehouses and locators using MWarehouse and MLocator, including locator coordinates, priorities, and defaults
  • How to query on-hand inventory using MStorageOnHand static methods — by product, warehouse, locator, and attribute set instance
  • How to create and process inventory transfers between locators using MMovement and MMovementLine
  • How Material Policy (FIFO/LIFO) determines which inventory lots are consumed first during movements and production
• Prerequisites: Lesson 24 — Production Overview
• Estimated reading time: 18 minutes

Introduction

Inventory management is at the heart of any ERP system. Knowing what you have, where it is, and being able to move it efficiently between locations are fundamental capabilities that support purchasing, production, sales, and financial reporting.

iDempiere provides a comprehensive inventory management system built around four key classes: MWarehouse (warehouse master data), MLocator (bin/location within a warehouse), MStorageOnHand (real-time inventory quantities), and MMovement (inventory transfer documents). In this lesson, you’ll learn how these components work together to track and manage inventory across your organization.

Warehouse Structure: MWarehouse and MLocator

MWarehouse — The Warehouse Master

A warehouse represents a physical or logical storage location within an organization. Each warehouse belongs to a single organization and can contain multiple locators (bins).

// Get a warehouse by ID (immutable, from cache)
MWarehouse warehouse = MWarehouse.get(ctx, warehouseId);
System.out.println("Warehouse: " + warehouse.getName());

// Get all warehouses for an organization
MWarehouse[] orgWarehouses = MWarehouse.getForOrg(ctx, orgId);
for (MWarehouse wh : orgWarehouses) {
    System.out.println("  " + wh.getValue() + " - " + wh.getName()
        + (wh.isInTransit() ? " [In Transit]" : ""));
}

// Get the default locator for a warehouse
MLocator defaultLocator = warehouse.getDefaultLocator();
System.out.println("Default locator: " + defaultLocator.getValue());

MLocator — Warehouse Bins and Locations

A locator represents a specific storage position within a warehouse. Locators use a three-dimensional coordinate system (X, Y, Z) to identify their physical location — think of it as aisle, rack, and shelf.

// Get a locator by ID (immutable, from cache)
MLocator locator = MLocator.get(ctx, locatorId);
System.out.println("Locator: " + locator.getValue()
    + " in warehouse " + locator.getWarehouseName());

// Get or create a locator by coordinates
// If a locator with these coordinates exists, it's returned;
// otherwise a new one is created
MLocator newLocator = MLocator.get(ctx, warehouseId,
    "LOC-A1-R3", "A1", "R3", "S1");  // value, X, Y, Z
newLocator.saveEx();

// Get default locator for a warehouse (highest priority)
MLocator defaultLoc = MLocator.getDefault(warehouse);

// Get all locators for a warehouse
MLocator[] locators = warehouse.getLocators(false);  // false = use cache
for (MLocator loc : locators) {
    System.out.println("  " + loc.getValue()
        + " [" + loc.getX() + "," + loc.getY() + "," + loc.getZ() + "]"
        + (loc.isDefault() ? " (default)" : ""));
}

Inventory Tracking: MStorageOnHand

MStorageOnHand is the real-time inventory ledger. Each record represents the quantity of a specific product at a specific locator with a specific attribute set instance (lot/serial number). The composite key is: M_Locator_ID + M_Product_ID + M_AttributeSetInstance_ID.

Querying Inventory

MStorageOnHand provides numerous static methods for querying inventory quantities:

// Get total on-hand quantity for a product in a warehouse
BigDecimal qtyOnHand = MStorageOnHand.getQtyOnHand(
    productId, warehouseId, 0,  // 0 = any ASI
    trxName);
System.out.println("Total on hand: " + qtyOnHand);

// Get on-hand quantity at a specific locator
BigDecimal qtyAtLocator = MStorageOnHand.getQtyOnHandForLocator(
    productId, locatorId, 0, trxName);
System.out.println("At locator: " + qtyAtLocator);

// Get all storage records for a product at a locator (with qty > 0)
MStorageOnHand[] storage = MStorageOnHand.getAll(
    ctx, productId, locatorId, trxName);
for (MStorageOnHand soh : storage) {
    System.out.println("  ASI=" + soh.getM_AttributeSetInstance_ID()
        + " qty=" + soh.getQtyOnHand()
        + " date=" + soh.getDateMaterialPolicy());
}

// Get warehouse-wide storage sorted by material policy (FIFO or LIFO)
MStorageOnHand[] warehouseStorage = MStorageOnHand.getWarehouse(
    ctx, warehouseId, productId,
    0,        // ASI (0 = any)
    null,     // min guarantee date
    true,     // FIFO order (false = LIFO)
    true,     // positive only
    0,        // locator filter (0 = all)
    trxName);
for (MStorageOnHand soh : warehouseStorage) {
    System.out.println("  Locator=" + soh.getM_Locator_ID()
        + " qty=" + soh.getQtyOnHand());
}

Updating Inventory

The primary method for modifying on-hand quantities is MStorageOnHand.add(). This method is called internally by document completion processes (MProduction, MMovement, MInOut) — you rarely call it directly, but understanding it is important:

// Add (or subtract) inventory at a locator
// This is called internally by MProduction.completeIt(), MMovement.completeIt(), etc.
boolean success = MStorageOnHand.add(
    ctx,
    locatorId,                    // where to add/subtract
    productId,                    // which product
    attributeSetInstanceId,       // which lot/serial (0 = no tracking)
    qty,                          // positive to add, negative to subtract
    dateMaterialPolicy,           // FIFO/LIFO date
    trxName);

// Note: If the warehouse has IsDisallowNegativeInv = true and the
// subtraction would result in negative inventory, this throws
// NegativeInventoryDisallowedException

Inventory Movement: MMovement

When you need to transfer inventory between locators — whether within the same warehouse or across different warehouses — you create an MMovement document. Like MProduction, MMovement implements DocAction and follows the standard document workflow.

MMovement Structure

MMovementLine — Transfer Line Items

Creating and Completing a Movement

// Step 1: Check source inventory
BigDecimal available = MStorageOnHand.getQtyOnHandForLocator(
    productId, fromLocatorId, 0, trxName);
BigDecimal transferQty = new BigDecimal("50");

if (available.compareTo(transferQty) < 0) {
    throw new AdempiereException("Insufficient stock: "
        + available + " available, " + transferQty + " required");
}

// Step 2: Create movement header
MMovement movement = new MMovement(ctx, 0, trxName);
movement.setAD_Org_ID(orgId);
movement.setMovementDate(new Timestamp(System.currentTimeMillis()));
movement.saveEx();

// Step 3: Create movement line
MMovementLine line = new MMovementLine(movement);
line.setM_Product_ID(productId);
line.setMovementQty(transferQty);
line.setM_Locator_ID(fromLocatorId);       // source
line.setM_LocatorTo_ID(toLocatorId);       // destination
line.saveEx();

// Step 4: Complete the movement
if (!movement.processIt(DocAction.ACTION_Complete)) {
    throw new AdempiereException("Movement failed: "
        + movement.getProcessMsg());
}
movement.saveEx();

System.out.println("Movement " + movement.getDocumentNo() + " completed");

// Step 5: Verify inventory updated
BigDecimal newSourceQty = MStorageOnHand.getQtyOnHandForLocator(
    productId, fromLocatorId, 0, trxName);
BigDecimal newDestQty = MStorageOnHand.getQtyOnHandForLocator(
    productId, toLocatorId, 0, trxName);

System.out.println("Source locator: " + newSourceQty);
System.out.println("Destination locator: " + newDestQty);

What Happens During Movement Completion

When completeIt() runs on an MMovement, the system:

1. Validates that source and destination locators are different (either locator or ASI must differ)
2. Checks for mandatory attribute set instances
3. For lines with ASI=0, auto-generates MMovementLineMA records based on the material policy (FIFO/LIFO)
4. Calls MStorageOnHand.add() to decrease inventory at the source locator
5. Calls MStorageOnHand.add() to increase inventory at the destination locator
6. Creates MTransaction records for the audit trail (MovementType: M+ for receipt, M- for shipment)

Material Policy: FIFO and LIFO

When consuming inventory — whether through production or movement — the system needs to know which specific inventory to consume. This is determined by the product's Material Policy, configured at the product category level.

FIFO (First In, First Out)

The oldest inventory (earliest DateMaterialPolicy) is consumed first. This is typical for perishable goods and is the most common policy. When querying storage with FIFO, records are sorted by DateMaterialPolicy ascending.

LIFO (Last In, First Out)

The newest inventory (latest DateMaterialPolicy) is consumed first. Less common, but used in some industries for tax optimization. Records are sorted by DateMaterialPolicy descending.

How Material Policy Affects Movements

// When a movement line has ASI = 0 (no specific lot selected),
// the system auto-allocates from available storage based on material policy.
//
// Example: Product has 3 storage records at the source locator:
//   Lot A: 30 units, received 2026-01-15
//   Lot B: 50 units, received 2026-02-01
//   Lot C: 20 units, received 2026-02-15
//
// Moving 60 units with FIFO policy:
//   - 30 units from Lot A (oldest)
//   - 30 units from Lot B (next oldest)
//
// Moving 60 units with LIFO policy:
//   - 20 units from Lot C (newest)
//   - 40 units from Lot B (next newest)

// Query storage in FIFO order
MStorageOnHand[] fifoStorage = MStorageOnHand.getWarehouse(
    ctx, warehouseId, productId,
    0,        // ASI
    null,     // guarantee date
    true,     // FiFo = true
    true,     // positive only
    0,        // locator filter
    trxName);

// Query storage in LIFO order
MStorageOnHand[] lifoStorage = MStorageOnHand.getWarehouse(
    ctx, warehouseId, productId,
    0, null,
    false,    // FiFo = false (LIFO)
    true, 0, trxName);

Key Takeaways

• MWarehouse represents physical storage facilities, each containing multiple MLocator bins identified by X/Y/Z coordinates. Use MWarehouse.get() for cached access and getDefaultLocator() for the primary receiving location.
• MStorageOnHand is the real-time inventory ledger, keyed by Locator + Product + ASI. Use its static query methods (getQtyOnHand, getAll, getWarehouse) to check stock levels, and understand that its add() method is called internally by document completion processes.
• MMovement handles inventory transfers between locators, following the standard DocAction workflow. Each MMovementLine specifies a product, quantity, source locator, and destination locator. On completion, the system updates MStorageOnHand for both locations.
• Material Policy (FIFO/LIFO) determines which inventory lots are consumed first. The DateMaterialPolicy field drives the consumption order, and the system auto-generates allocation records when no specific lot is selected. Note that FIFO and LIFO also serve as costing methods in the Accounting Schema — the material policy and costing method work together to determine both consumption order and cost valuation.
• Always validate stock availability before creating movements to avoid errors, especially when IsDisallowNegativeInv is enabled on the warehouse.

What's Next

In the Advanced level, Advanced Production & BOM Management covers multi-product production plans (MProductionPlan), lot tracking with MProductionLineMA, BOM verification, and phantom assembly expansion in depth.

// Get a warehouse by ID (immutable, from cache)
MWarehouse warehouse = MWarehouse.get(ctx, warehouseId);
System.out.println("Warehouse: " + warehouse.getName());

// Get all warehouses for an organization
MWarehouse[] orgWarehouses = MWarehouse.getForOrg(ctx, orgId);
for (MWarehouse wh : orgWarehouses) {
    System.out.println("  " + wh.getValue() + " - " + wh.getName()
        + (wh.isInTransit() ? " [In Transit]" : ""));
}

// Get the default locator for a warehouse
MLocator defaultLocator = warehouse.getDefaultLocator();
System.out.println("Default locator: " + defaultLocator.getValue());

// Get a locator by ID (immutable, from cache)
MLocator locator = MLocator.get(ctx, locatorId);
System.out.println("Locator: " + locator.getValue()
    + " in warehouse " + locator.getWarehouseName());

// Get or create a locator by coordinates
// If a locator with these coordinates exists, it's returned;
// otherwise a new one is created
MLocator newLocator = MLocator.get(ctx, warehouseId,
    "LOC-A1-R3", "A1", "R3", "S1");  // value, X, Y, Z
newLocator.saveEx();

// Get default locator for a warehouse (highest priority)
MLocator defaultLoc = MLocator.getDefault(warehouse);

// Get all locators for a warehouse
MLocator[] locators = warehouse.getLocators(false);  // false = use cache
for (MLocator loc : locators) {
    System.out.println("  " + loc.getValue()
        + " [" + loc.getX() + "," + loc.getY() + "," + loc.getZ() + "]"
        + (loc.isDefault() ? " (default)" : ""));
}

// Get total on-hand quantity for a product in a warehouse
BigDecimal qtyOnHand = MStorageOnHand.getQtyOnHand(
    productId, warehouseId, 0,  // 0 = any ASI
    trxName);
System.out.println("Total on hand: " + qtyOnHand);

// Get on-hand quantity at a specific locator
BigDecimal qtyAtLocator = MStorageOnHand.getQtyOnHandForLocator(
    productId, locatorId, 0, trxName);
System.out.println("At locator: " + qtyAtLocator);

// Get all storage records for a product at a locator (with qty > 0)
MStorageOnHand[] storage = MStorageOnHand.getAll(
    ctx, productId, locatorId, trxName);
for (MStorageOnHand soh : storage) {
    System.out.println("  ASI=" + soh.getM_AttributeSetInstance_ID()
        + " qty=" + soh.getQtyOnHand()
        + " date=" + soh.getDateMaterialPolicy());
}

// Get warehouse-wide storage sorted by material policy (FIFO or LIFO)
MStorageOnHand[] warehouseStorage = MStorageOnHand.getWarehouse(
    ctx, warehouseId, productId,
    0,        // ASI (0 = any)
    null,     // min guarantee date
    true,     // FIFO order (false = LIFO)
    true,     // positive only
    0,        // locator filter (0 = all)
    trxName);
for (MStorageOnHand soh : warehouseStorage) {
    System.out.println("  Locator=" + soh.getM_Locator_ID()
        + " qty=" + soh.getQtyOnHand());
}

// Add (or subtract) inventory at a locator
// This is called internally by MProduction.completeIt(), MMovement.completeIt(), etc.
boolean success = MStorageOnHand.add(
    ctx,
    locatorId,                    // where to add/subtract
    productId,                    // which product
    attributeSetInstanceId,       // which lot/serial (0 = no tracking)
    qty,                          // positive to add, negative to subtract
    dateMaterialPolicy,           // FIFO/LIFO date
    trxName);

// Note: If the warehouse has IsDisallowNegativeInv = true and the
// subtraction would result in negative inventory, this throws
// NegativeInventoryDisallowedException

// Step 1: Check source inventory
BigDecimal available = MStorageOnHand.getQtyOnHandForLocator(
    productId, fromLocatorId, 0, trxName);
BigDecimal transferQty = new BigDecimal("50");

if (available.compareTo(transferQty) < 0) {
    throw new AdempiereException("Insufficient stock: "
        + available + " available, " + transferQty + " required");
}

// Step 2: Create movement header
MMovement movement = new MMovement(ctx, 0, trxName);
movement.setAD_Org_ID(orgId);
movement.setMovementDate(new Timestamp(System.currentTimeMillis()));
movement.saveEx();

// Step 3: Create movement line
MMovementLine line = new MMovementLine(movement);
line.setM_Product_ID(productId);
line.setMovementQty(transferQty);
line.setM_Locator_ID(fromLocatorId);       // source
line.setM_LocatorTo_ID(toLocatorId);       // destination
line.saveEx();

// Step 4: Complete the movement
if (!movement.processIt(DocAction.ACTION_Complete)) {
    throw new AdempiereException("Movement failed: "
        + movement.getProcessMsg());
}
movement.saveEx();

System.out.println("Movement " + movement.getDocumentNo() + " completed");

// Step 5: Verify inventory updated
BigDecimal newSourceQty = MStorageOnHand.getQtyOnHandForLocator(
    productId, fromLocatorId, 0, trxName);
BigDecimal newDestQty = MStorageOnHand.getQtyOnHandForLocator(
    productId, toLocatorId, 0, trxName);

System.out.println("Source locator: " + newSourceQty);
System.out.println("Destination locator: " + newDestQty);

// When a movement line has ASI = 0 (no specific lot selected),
// the system auto-allocates from available storage based on material policy.
//
// Example: Product has 3 storage records at the source locator:
//   Lot A: 30 units, received 2026-01-15
//   Lot B: 50 units, received 2026-02-01
//   Lot C: 20 units, received 2026-02-15
//
// Moving 60 units with FIFO policy:
//   - 30 units from Lot A (oldest)
//   - 30 units from Lot B (next oldest)
//
// Moving 60 units with LIFO policy:
//   - 20 units from Lot C (newest)
//   - 40 units from Lot B (next newest)

// Query storage in FIFO order
MStorageOnHand[] fifoStorage = MStorageOnHand.getWarehouse(
    ctx, warehouseId, productId,
    0,        // ASI
    null,     // guarantee date
    true,     // FiFo = true
    true,     // positive only
    0,        // locator filter
    trxName);

// Query storage in LIFO order
MStorageOnHand[] lifoStorage = MStorageOnHand.getWarehouse(
    ctx, warehouseId, productId,
    0, null,
    false,    // FiFo = false (LIFO)
    true, 0, trxName);

// Get a warehouse by ID (immutable, from cache)
MWarehouse warehouse = MWarehouse.get(ctx, warehouseId);
System.out.println("Warehouse: " + warehouse.getName());

// Get all warehouses for an organization
MWarehouse[] orgWarehouses = MWarehouse.getForOrg(ctx, orgId);
for (MWarehouse wh : orgWarehouses) {
    System.out.println("  " + wh.getValue() + " - " + wh.getName()
        + (wh.isInTransit() ? " [In Transit]" : ""));
}

// Get the default locator for a warehouse
MLocator defaultLocator = warehouse.getDefaultLocator();
System.out.println("Default locator: " + defaultLocator.getValue());

// Get a locator by ID (immutable, from cache)
MLocator locator = MLocator.get(ctx, locatorId);
System.out.println("Locator: " + locator.getValue()
    + " in warehouse " + locator.getWarehouseName());

// Get or create a locator by coordinates
// If a locator with these coordinates exists, it's returned;
// otherwise a new one is created
MLocator newLocator = MLocator.get(ctx, warehouseId,
    "LOC-A1-R3", "A1", "R3", "S1");  // value, X, Y, Z
newLocator.saveEx();

// Get default locator for a warehouse (highest priority)
MLocator defaultLoc = MLocator.getDefault(warehouse);

// Get all locators for a warehouse
MLocator[] locators = warehouse.getLocators(false);  // false = use cache
for (MLocator loc : locators) {
    System.out.println("  " + loc.getValue()
        + " [" + loc.getX() + "," + loc.getY() + "," + loc.getZ() + "]"
        + (loc.isDefault() ? " (default)" : ""));
}

// Get total on-hand quantity for a product in a warehouse
BigDecimal qtyOnHand = MStorageOnHand.getQtyOnHand(
    productId, warehouseId, 0,  // 0 = any ASI
    trxName);
System.out.println("Total on hand: " + qtyOnHand);

// Get on-hand quantity at a specific locator
BigDecimal qtyAtLocator = MStorageOnHand.getQtyOnHandForLocator(
    productId, locatorId, 0, trxName);
System.out.println("At locator: " + qtyAtLocator);

// Get all storage records for a product at a locator (with qty > 0)
MStorageOnHand[] storage = MStorageOnHand.getAll(
    ctx, productId, locatorId, trxName);
for (MStorageOnHand soh : storage) {
    System.out.println("  ASI=" + soh.getM_AttributeSetInstance_ID()
        + " qty=" + soh.getQtyOnHand()
        + " date=" + soh.getDateMaterialPolicy());
}

// Get warehouse-wide storage sorted by material policy (FIFO or LIFO)
MStorageOnHand[] warehouseStorage = MStorageOnHand.getWarehouse(
    ctx, warehouseId, productId,
    0,        // ASI (0 = any)
    null,     // min guarantee date
    true,     // FIFO order (false = LIFO)
    true,     // positive only
    0,        // locator filter (0 = all)
    trxName);
for (MStorageOnHand soh : warehouseStorage) {
    System.out.println("  Locator=" + soh.getM_Locator_ID()
        + " qty=" + soh.getQtyOnHand());
}

// Add (or subtract) inventory at a locator
// This is called internally by MProduction.completeIt(), MMovement.completeIt(), etc.
boolean success = MStorageOnHand.add(
    ctx,
    locatorId,                    // where to add/subtract
    productId,                    // which product
    attributeSetInstanceId,       // which lot/serial (0 = no tracking)
    qty,                          // positive to add, negative to subtract
    dateMaterialPolicy,           // FIFO/LIFO date
    trxName);

// Note: If the warehouse has IsDisallowNegativeInv = true and the
// subtraction would result in negative inventory, this throws
// NegativeInventoryDisallowedException

// Step 1: Check source inventory
BigDecimal available = MStorageOnHand.getQtyOnHandForLocator(
    productId, fromLocatorId, 0, trxName);
BigDecimal transferQty = new BigDecimal("50");

if (available.compareTo(transferQty) < 0) {
    throw new AdempiereException("Insufficient stock: "
        + available + " available, " + transferQty + " required");
}

// Step 2: Create movement header
MMovement movement = new MMovement(ctx, 0, trxName);
movement.setAD_Org_ID(orgId);
movement.setMovementDate(new Timestamp(System.currentTimeMillis()));
movement.saveEx();

// Step 3: Create movement line
MMovementLine line = new MMovementLine(movement);
line.setM_Product_ID(productId);
line.setMovementQty(transferQty);
line.setM_Locator_ID(fromLocatorId);       // source
line.setM_LocatorTo_ID(toLocatorId);       // destination
line.saveEx();

// Step 4: Complete the movement
if (!movement.processIt(DocAction.ACTION_Complete)) {
    throw new AdempiereException("Movement failed: "
        + movement.getProcessMsg());
}
movement.saveEx();

System.out.println("Movement " + movement.getDocumentNo() + " completed");

// Step 5: Verify inventory updated
BigDecimal newSourceQty = MStorageOnHand.getQtyOnHandForLocator(
    productId, fromLocatorId, 0, trxName);
BigDecimal newDestQty = MStorageOnHand.getQtyOnHandForLocator(
    productId, toLocatorId, 0, trxName);

System.out.println("Source locator: " + newSourceQty);
System.out.println("Destination locator: " + newDestQty);

// When a movement line has ASI = 0 (no specific lot selected),
// the system auto-allocates from available storage based on material policy.
//
// Example: Product has 3 storage records at the source locator:
//   Lot A: 30 units, received 2026-01-15
//   Lot B: 50 units, received 2026-02-01
//   Lot C: 20 units, received 2026-02-15
//
// Moving 60 units with FIFO policy:
//   - 30 units from Lot A (oldest)
//   - 30 units from Lot B (next oldest)
//
// Moving 60 units with LIFO policy:
//   - 20 units from Lot C (newest)
//   - 40 units from Lot B (next newest)

// Query storage in FIFO order
MStorageOnHand[] fifoStorage = MStorageOnHand.getWarehouse(
    ctx, warehouseId, productId,
    0,        // ASI
    null,     // guarantee date
    true,     // FiFo = true
    true,     // positive only
    0,        // locator filter
    trxName);

// Query storage in LIFO order
MStorageOnHand[] lifoStorage = MStorageOnHand.getWarehouse(
    ctx, warehouseId, productId,
    0, null,
    false,    // FiFo = false (LIFO)
    true, 0, trxName);