1. What MSI actually models in Magento 2

MSI Magento 2 stands for Multi Source Inventory and, for the first time, cleanly separates physical sources, logical stocks and salable quantity. This matters because in real projects, inventory rarely consists of a single number. There are warehouses, branch stores, fulfillment partners, buffer stock and reservations from orders that have not yet been fully completed.

That is precisely why you should not read MSI Magento 2 as a mere replacement for the old stock field. A source is a physical or organizational point of origin. A stock bundles availability for a sales channel. Salable quantity then does not simply come from "stock minus something", but from several layers, including reservations. Anyone who blends these layers inevitably ends up with wrong reports or broken integrations.

In real projects this often only becomes visible under load. As long as there are only a few products and a few orders, everything feels intuitive. Once returns, partial shipments, different fulfillment paths or external ERP synchronizations enter the picture, it becomes clear that MSI Magento 2 is a domain model, not just an admin screen for stock numbers.

2. Creating and thinking about a Custom Source in Magento 2

Creating a Custom Source Magento 2 is technically simple, but it should be prepared with proper domain thinking. The core question is not just "how do I create a new source?" but "what real or logical function does this source represent in the business process?" A warehouse in Berlin, a dropshipping partner or a returns warehouse are different business objects with different consequences for availability and shipping.

That is exactly why a Custom Source Magento 2 should not be misused as a quick workaround for arbitrary edge cases. If the source in reality only represents an attribute of a stock or a delivery preference, a new source is often the wrong model. Sources are powerful structural elements. They should only be introduced when they genuinely play an independent role in operations, logistics or integration logic.

<?php
declare(strict_types=1);

use Magento\InventoryApi\Api\Data\SourceInterfaceFactory;
use Magento\InventoryApi\Api\SourceRepositoryInterface;

$source = $sourceFactory->create();
$source->setSourceCode('warehouse_berlin');
$source->setName('Warehouse Berlin');
$source->setEnabled(true);
$source->setCountryId('DE');
$source->setPostcode('10115');
$source->setCity('Berlin');
$source->setStreet('Example Street 1');

$sourceRepository->save($source);

This example only shows the basic idea. In real projects that is not enough. A Custom Source Magento 2 must be considered in assignment, source items, stocks, fulfillment rules and integrations. Just because a source exists does not mean it is correctly wired into the business flow.

3. Understanding reservations in Magento 2

Reservations are one of the most commonly misunderstood parts of MSI Magento 2. Many developers expect every order to immediately reduce the physical source stock. In reality, Magento uses reservations to influence salable quantity before the entire fulfillment process has been finally booked. This matters because order, payment, shipment, cancellation and returns can happen at different points in time.

In practice this means: salable quantity often reacts earlier than the physical stock of a specific source. This difference is not a bug, it is part of the model. If you ignore reservations, reports or API values quickly appear contradictory. Once you understand them, the behavior of MSI Magento 2 forms a traceable chain: salability is secured before final stock bookings are completed.

bin/magento inventory:reservation:list-inconsistencies
bin/magento inventory:reservation:create-compensations

These commands are extremely valuable in projects because they help identify inconsistencies between the order flow and the reservation state. Especially during imports, migrations or with faulty third-party modules, this is often the level at which the truth becomes visible.

4. Data flow between Source Items, Stocks and Salable Quantity

A solid understanding of MSI Magento 2 only emerges once you think through the data flow end to end. Source items describe the assignment of a product to a source and its respective quantity. Stocks bundle sources for a sales channel. Salable quantity results from stock, assignments and reservations. These layers are related, but not identical.

This is exactly where many teams make mistakes in custom development and integrations. They read a single value from a table and call it "stock", even though what they actually mean, in business terms, is salability. Or they overwrite source quantities directly, even though the problem lies in reservations or stock assignments. Anyone working with MSI Magento 2 must therefore always ask: which specific stock am I interested in? Physical, channel-related, or salable?

<?php
declare(strict_types=1);

use Magento\InventoryApi\Api\SourceItemsSaveInterface;
use Magento\InventoryApi\Api\Data\SourceItemInterfaceFactory;

$sourceItem = $sourceItemFactory->create();
$sourceItem->setSourceCode('warehouse_berlin');
$sourceItem->setSku('demo-sku');
$sourceItem->setQuantity(25.0);
$sourceItem->setStatus(1);

$sourceItemsSave->execute([$sourceItem]);

Updates like this should never be viewed in isolation. Every quantity change on a source affects downstream availability calculations. Good implementations therefore treat MSI Magento 2 as a system of states, not as individual columns holding numbers.

5. Typical extension scenarios with MSI

Typical projects extend MSI Magento 2 for store-level availability, dropshipping, B2B availability, external ERP systems, marketplace connections or channel-dependent fulfillment rules. In all of these cases, the core task is not just "write stock", but a stable translation between external business processes and the MSI model.

A good extension therefore starts by asking about the domain. Should a source represent a real physical location? Should it only delimit a specific fulfillment pattern? Does the project need genuine channel-related stocks, or just differentiated reporting layers? These questions determine whether MSI Magento 2 becomes a problem solver or additional complexity.

Particularly risky are integrations that keep old single-stock assumptions "just to be safe" and only serve MSI superficially. Source items get written, but salable quantity or reservations get ignored in reporting, export or checkout logic. That is exactly where the expensive inconsistencies show up later.

6. Common mistakes

The most common mistakes are conceptual. Teams confuse source and stock. They interpret salable quantity as physical stock. They ignore reservations. They introduce new sources when what actually needed to be modeled was not a new source but a different process state. Or they overwrite data directly in database tables, bypassing the domain APIs of MSI Magento 2.

Another frequent mistake is debugging at the wrong level. When a product appears unavailable, teams often only look at source quantities. But the problem might actually lie in stock assignments, in the reservation state, or in a faulty compensation run. Good diagnosis starts with the business question and then looks for the matching layer in the MSI model.

Third-party modules are also a risk. Extensions built around old stock thinking can produce unclear side effects with MSI Magento 2. In such cases, a single fix at one spot is often not enough. Then the entire inventory logic needs to be reviewed as a whole.

7. MSI versus classic single-stock thinking

The difference between MSI Magento 2 and classic single-stock thinking is not just technical layering, it is domain precision. Single stock, at its core, knows one warehouse number. MSI, by contrast, separates origin, channel assignment and salability. This is more effort, but for realistic fulfillment scenarios it is often indispensable.

MSI is therefore not an end in itself. It pays off exactly where business reality is more than a single warehouse number. Anyone who understands that can use the system in a lean and precise way, instead of over-modeling it unnecessarily.

9. Summary

MSI Magento 2 deliberately separates sources, stocks and salability. Anyone who respects these layers can cleanly model multi-warehouse, multi-channel and fulfillment scenarios. Anyone who blends them will, sooner or later, produce stock errors, broken integrations or wrong reports.

The most important practical rule remains: do not just look at quantities, always name the business layer. Is it about physical stock, channel-related availability, or salable quantity? Only with this clarity does MSI become manageable in a project.

10. FAQ: MSI in Magento 2