Magento Inventory and Stock Management — Multi-Source Inventory Guide

In this tutorial, you'll learn how Magento handles inventory management through the Multi-Source Inventory (MSI) system, including sources, stocks, backorders, stock thresholds, and inventory reporting.

What You'll Learn

• How Multi-Source Inventory (MSI) works with sources and stocks
• Creating and managing physical inventory sources
• Configuring stocks and linking them to sales channels
• Assigning inventory sources to products with quantities
• Managing backorders, stock thresholds, and quantity increments
• Understanding backorder behavior and stock reservation
• Using inventory reports and CLI commands
• Distance-based source selection algorithm for shipping

Why It Matters

Inventory management is where e-commerce meets real-world logistics. A store that shows products in stock but cannot fulfill them loses customer trust permanently. MSI allows Magento to track inventory across multiple warehouses, retail stores, and distribution centers in real time. Understanding how sources, stocks, and reservations work ensures you never oversell a product or disappoint a customer.

Real-World Use

A retailer has three warehouses: New York (East Coast), Chicago (Central), and Los Angeles (West Coast). When a customer in San Francisco orders a product, Magento checks which warehouse has stock. It reserves the stock from LA (closest to the customer) and updates inventory in real time. If no single warehouse has enough stock, Magento can split the shipment across multiple sources.

Learning Path

flowchart LR
  A["Pricing & Catalog Rules"] --> B["Inventory & Stock
← You are here"]:::current
  B --> C["Cart & Checkout"]
  C --> D["Payment Gateways"]
  D --> E["Shipping"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

Multi-Source Inventory (MSI)

MSI was introduced in Magento 2.3 and completely replaced the legacy inventory system. It is the default inventory management system in Magento 2.4 and later.

MSI introduces two core concepts:

• Sources — Physical locations where inventory is stored (warehouses, retail stores, distribution centers)
• Stocks — Virtual aggregations of sources linked to sales channels (websites)

A single source can belong to multiple stocks. A stock aggregates multiple sources and is linked to one or more sales channels.

This architecture supports:

• Single-source merchants: one warehouse, one stock
• Multi-source merchants: multiple warehouses, aggregated into one or multiple stocks
• Multi-channel merchants: different stocks for different websites (B2C vs B2B)

Sources

A source is a physical location. Go to Stores > Inventory > Sources to manage them.

Each source has:

• Name and Code — Internal identifiers. The code is used in API calls and CLI commands.
• Country, State, Post Code, City, Street — Physical address. Used for distance-based source selection.
• Contact Info — Name, email, phone for warehouse contacts.
• GPS Coordinates — Latitude and longitude for distance calculations.

Magento comes with a "Default" source. You cannot delete it because it is used for products that were created before MSI was enabled. For modern installations, create custom sources for each physical location.

To add a source:

php bin/magento inventory:source:create --name "New York Warehouse" --code ny_warehouse

Or add via the admin panel: Stores > Inventory > Sources > Add New Source.

Stocks

A stock is a virtual aggregation of sources, linked to sales channels.

Go to Stores > Inventory > Stocks to manage them.

When creating a stock:

1. Give it a name (e.g., "North America Stock").
2. Assign the stock to sales channels (websites).
3. Assign sources that feed into this stock.

For example, if you have warehouses in New York, Chicago, and Dallas serving US customers, create a "US Stock" that aggregates all three sources and assign it to your US website.

Magento also has a "Default Stock" that includes the Default Source and is assigned to the main website.

Assigning Sources to Products

For each product, you specify which sources have stock and at what quantities.

Edit a product and go to the Sources section. For each source, set:

• Qty — The current stock quantity at that source
• Status — In Stock or Out of Stock
• Notify Quantity Below — When stock drops to this level, Magento sends a notification

Example for a product with two sources:

Source: New York Warehouse
  Qty: 50
  Status: In Stock
  Notify Quantity Below: 10

Source: Los Angeles Warehouse
  Qty: 25
  Status: In Stock
  Notify Quantity Below: 5

When a customer orders this product, Magento selects the best source based on the distance algorithm and reserves the stock from that source.

Stock Management Per Product

Beyond simple source quantities, each product has advanced stock settings:

• Min Qty — Minimum stock level before the product is marked out of stock
• Min Shopping Cart — Minimum quantity per order
• Max Shopping Cart — Maximum quantity per order
• Backorders — No backorders, Allow Qty Below Zero, Allow Qty Below Zero + Notify Customer
• Out of Stock Threshold — Threshold for triggering notifications
• Enable Qty Increments — Force customers to buy in increments (e.g., multiples of 5)

Go to the Advanced Inventory section of the product form to configure these.

Backorders

Backorders let customers purchase products that are currently out of stock. Magento offers three modes:

No Backorders. If stock is zero or negative, the product cannot be purchased. This is the safest mode — you never oversell.

Allow Qty Below Zero. Stock can go negative. Customers can place orders even when stock is zero. You fulfill these orders when new stock arrives. The stock counter shows negative numbers.

Allow Qty Below Zero + Notify Customer. Same as above, but the customer sees a "Usually ships in X days" message on the product page.

Backorder behavior:

• The product remains purchasable even when stock reaches zero
• Stock quantity goes negative (e.g., -10 means 10 backorders pending)
• The backordered items are included in order totals and payment processing
• The stock reservation algorithm reserves the ordered quantity

Configure backorders carefully. Without proper planning, customers may order products you cannot fulfill for weeks.

Inventory Reports

Magento provides several inventory reports:

• Low Stock Report — Products > Inventory > Low Stock Report. Shows products with quantity below the notification threshold.
• Stock per Source — The product edit page shows stock per source. The inventory index aggregates this for front-end display.
• Order Reservations — The order management section shows reserved quantities per order.
• Indexes — The inventory index converts per-source stock into salable quantities per stock.

Inventory CLI Commands

MSI includes several CLI commands for bulk inventory operations:

# Assign sources to products in bulk
php bin/magento inventory:source:assign-products <source_code> <product_skus>

# Update stock reservations
php bin/magento inventory:reservation:update <order_id> <increment_id>

# List sources
php bin/magento inventory:source:list

# Create a source
php bin/magento inventory:source:create --name "Source Name" --code source_code

These commands are useful for automated inventory updates from an external ERP system.

Distance-Based Source Selection

When a customer places an order, Magento must decide which source(s) to fulfill from. The distance-based source selection algorithm picks the geographically closest source with sufficient stock.

The algorithm uses:

1. The customer's shipping address
2. The GPS coordinates of each source
3. The distance calculation configured in Stores > Configuration > Catalog > Inventory > Distance Based SPC

You can enter GPS coordinates for each source via the source management form. The algorithm computes the distance and selects the nearest source with available stock.

Inventory Indexes

MSI uses several indexers:

• Inventory Index — Computes salable quantity per stock per product
• Catalog Search Index — Includes stock status for search results
• Stock Index — Tracks reservations and available quantities

Reindex after bulk inventory changes:

php bin/magento indexer:reindex inventory

Common Mistakes

1. Not configuring MSI correctly for single-source stores. Many single-source merchants leave the Default stock and Default source as-is, which works. But they should verify the Default source has the correct address, contact info, and GPS coordinates for distance calculations.

2. Setting backorders without a fulfillment plan. Allowing backorders without supplier agreements or restock timelines creates unhappy customers. Only enable backorders if you have a reliable restocking Process within 1-2 weeks.

3. Ignoring the notification threshold. The "Notify Quantity Below" setting sends alerts to the admin. Without it configured, you may not know a product is running low until it is completely out of stock.

4. Forgetting to reindex after bulk updates. Importing products with inventory quantities without reindexing the inventory index means the store shows incorrect stock levels. Always run php bin/magento indexer:reindex inventory after bulk imports.

5. Overselling across multiple sources with the same stock. If a stock aggregates multiple sources but a customer can order from different sessions before the reservation updates, overselling can occur. The reservation system mitigates this but cannot prevent it entirely in high-concurrency scenarios.

Practice Questions

1. What is the difference between a source and a stock in MSI? Answer: A source is a physical location where inventory is stored (warehouse, retail store). A stock is a virtual aggregation of sources linked to sales channels (websites). Multiple sources can feed into one stock, and one source can belong to multiple stocks.

2. How does the distance-based source selection algorithm work? Answer: When a customer places an order, Magento checks all sources assigned to the relevant stock. It calculates the distance between the customer's shipping address and each source's GPS coordinates. The source with sufficient stock closest to the customer is selected for fulfillment.

3. What happens when backorders are enabled and stock reaches zero? Answer: The product remains purchasable. Stock quantity goes negative to track pending backorders (e.g., -5 means 5 backorders). The ordered quantity is reserved. Customers can checkout normally. Restocking brings the number back toward zero.

4. Challenge: Set up a multi-source inventory system for a retailer with three warehouses (New York, Chicago, Los Angeles) serving the US and a separate warehouse (London) serving the UK. Create two stocks: US Stock (aggregating NY, Chicago, LA) linked to the US website, and UK Stock (aggregating London) linked to the UK website. Assign GPS coordinates to each source. Create a test product with quantities at each source. Place test orders from US and UK addresses and verify the correct source is selected.

FAQ

Mini Project

Your task: Build a multi-source inventory system for a national retailer.

1. Create three sources:
   • "Northeast DC" (New York) — Qty: 100
   • "Southeast DC" (Atlanta) — Qty: 75
   • "West Coast DC" (Los Angeles) — Qty: 50
2. Create one stock "US Main Stock" aggregating all three sources, linked to the main website.
3. Create a product "Ergonomic Office Chair" and assign quantities to each source.
4. Configure notification threshold (15 units) for each source.
5. Enable backorders with "Allow Qty Below Zero + Notify Customer."
6. Place test orders from different shipping addresses and verify source selection.
7. Check the Low Stock Report to see which sources need restocking.
8. Use CLI commands to transfer stock between sources (simulate warehouse transfer).

This exercise prepares you to manage real-world inventory in production Magento stores.

What's Next

Now that you understand inventory, learn how the shopping cart and checkout process works:

Continue to Lesson 9: Shopping Cart and Checkout — Complete sales workflow.

Related lessons:

• Orders, Invoices and Shipments — The order lifecycle
• Shipping — Shipping methods and carriers
• What is Magento — MSI architecture overview