When a Magento order ships from multiple warehouses, the Source Selection Algorithm decides which source fulfills each item. Native Magento gives you two: Source Priority, which walks a ranked list, and Distance Priority, which picks the closest warehouse. Both can split an order across sources, and when neither fits your logic, you can write your own.
Source Selection is the quiet engine behind multi-warehouse fulfillment. Get it right and orders ship from the cheapest or closest source with the fewest parcels. Get it wrong and a two-item order splits into two shipments from opposite coasts. This guide covers how the native algorithms behave, where they fall short, and how to implement a custom algorithm against the Source Selection interface. For the storefront side of inventory, see our Magento development services.
Where Source Selection fits in MSI
Multi-Source Inventory (MSI) models stock as quantities held at named sources, grouped into stocks that map to sales channels, as Adobe’s sources and stocks documentation lays out. When an order is ready to ship, the Source Selection Algorithm takes the requested SKUs, quantities, and the shipping address, and returns a recommendation: which source should deduct how much of each item. A merchant can accept that recommendation or adjust it, reassigning sources or quantities before creating the shipment.
That recommendation is where the split happens. Because the algorithm allocates per item, an order can end up drawing from several sources, which means several shipments. Minimizing that is the whole game. Our guide to Multi-Source Inventory on a Hyva Magento storefront covers how salable quantity is calculated and displayed, which is the input to all of this, and inventory reservations explains how the quantities stay honest between order and shipment.
Source Priority: the default ranked walk
Source Priority is the default. For each product in the order, it walks the configured source list for the relevant stock, from the top, skipping disabled sources, and keeps going until the requested quantity is covered. The output is a recommended source and quantity per product, based on list order, available quantity, and quantity ordered.
The behavior to understand: the walk is per product, independent of the other items in the order. So if your top-priority source has item A but not item B, and a lower source has item B, the order splits. Source Priority never looks at the order as a whole to ask “which single source could ship everything.” It just fills each line from the ranked list.
That makes Source Priority predictable and simple, and a good fit when one primary warehouse holds most stock and the ranking reflects a real preference, like shipping from your main fulfillment center first and a backup second.
Distance Priority: closest source wins
Distance Priority routes by geography. It compares the shipping destination against each source’s location and prefers the closest source. There are two ways it computes distance:
- Google Maps mode uses the Google Maps Platform to calculate real distance and time between the destination and each source. It needs a Google Maps API key and bills against your Google usage.
- Offline mode uses imported geocode data and the country codes of the address and sources. It avoids per-request API cost, but a developer has to download and import the geocode data through the command line first.
| Source Priority | Distance Priority | |
|---|---|---|
| Routes by | Ranked source list | Geographic distance |
| Needs external API | No | Only in Google Maps mode |
| Setup | Order the source list | Import geocodes or set up Google Maps |
| Best for | One dominant warehouse, clear ranking | Regional warehouses, cutting transit time |
| Split behavior | Per-item down the list | Per-item by nearest source |
MGT-Commerce’s Multi-Source Inventory tutorial walks through configuring sources and the regional-shipping payoff in practice. Distance Priority shines when you run regional warehouses and want to cut transit time and zone-based shipping cost. The caveat is the same as Source Priority: it ranks sources per item, so it still does not explicitly minimize the number of shipments. A nearby source that lacks one item will still send you to a second source for that item.
A concrete split scenario
Picture two sources: East (New Jersey) and West (Nevada). A customer in Pennsylvania orders a jacket and a hat. East has the jacket but is out of the hat; West has both. Under Distance Priority, East is closer to Pennsylvania, so the jacket ships from East. The hat is not at East, so the algorithm goes to the next source, West, for the hat. The result is two shipments for a two-item order, even though West alone could have shipped both in one parcel. That is not a bug. It is the per-item ranking doing exactly what it is designed to do. Recognizing this pattern is the first step to fixing it, because the fix depends on whether you care more about transit distance or parcel count.
Why orders split, and how to reduce it
Neither native algorithm optimizes for the fewest parcels, because both rank sources rather than solving the whole order at once. The practical levers to reduce splitting:
- Stock the right items together. If your top source carries the full catalog, Source Priority rarely splits. Splits are usually an inventory distribution problem before they are an algorithm problem.
- Adjust the recommendation. The algorithm’s output is editable at shipment time. For high-value or split-prone orders, a human or an OMS can consolidate to one source.
- Use a fewest-sources algorithm. Several commercial extensions add a “product stock availability” mode that picks the single source holding every item in the order, which directly avoids splitting when one source can cover it.
- Hand it to an OMS. If routing logic gets complex, an order management system often owns it. Our guide to connecting a 3PL to Magento and Hyva covers where fulfillment routing moves out of Magento entirely.
Writing a custom Source Selection algorithm
When the native options and extensions do not express your rule, you implement your own. The shape, per the Magento inventory project:
- Implement the interface. Create a class that implements the source selection interface for your version (historically
SourceSelectionInterface, later revisions useSourceSelectionAlgorithmInterfacewith an algorithm-type argument). Itsexecute()method receives an inventory request and returns a result object. Confirm the exact interface and namespace against the source for your Magento version, because it changed across releases. - Read the request. Pull the requested SKUs, quantities, and shipping address from the inventory request.
- Allocate. Query each source’s salable quantity for those SKUs, then build a result that assigns each SKU across sources according to your rule: lowest delivery cost, fewest sources, a custom priority, or a blend. Allowing a split is what produces a partial shipment; preventing one means refusing to allocate unless a single source covers the order.
- Return the result. The result holds one entry per source and item with the quantity to deduct.
- Register it. Add the class to the
SourceSelectionServicethroughdi.xml, keyed by a unique algorithm name, so Magento knows the method exists. Then select it as the active algorithm in the inventory configuration.
The reference implementation the Magento inventory Source Selection wiki ships is a minimal delivery-cost algorithm, which is a good template because delivery cost is a real-world objective that neither native algorithm models directly.
Fulfillment routing on other platforms
Multi-location fulfillment routing is a common need, and platforms expose very different amounts of control:
- Adobe Commerce MSI gives you two native algorithms and a real extension point to write your own, which is the most control of the group.
- Teams on Shopify development get location-based inventory and Shopify’s own fulfillment routing, which is simpler but less customizable at the algorithm level.
- BigCommerce development and Shopware development each model multi-location stock differently, often leaning on apps or an OMS for advanced routing.
If your routing rules are genuinely custom, the Magento extension point is a real advantage. The team at Bemeir builds multi-warehouse fulfillment on Adobe Commerce and Hyva, and our technology partners include the OMS and shipping integrations that routing usually touches. For store-pickup routing specifically, see our guide to BOPIS on Magento and Hyva.
FAQ
What is the Source Selection Algorithm in Magento?
It is the MSI component that decides which inventory source fulfills each item in an order. It takes the requested SKUs, quantities, and shipping address, and returns a recommended source and quantity per item. Magento ships Source Priority and Distance Priority, and the recommendation is editable before the shipment is created.
What is the difference between Source Priority and Distance Priority?
Source Priority walks a ranked list of sources per product until the quantity is filled, so it suits one dominant warehouse with a clear ranking. Distance Priority picks the source geographically closest to the destination, using either the Google Maps API or imported offline geocodes, which suits regional warehouses aiming to cut transit time.
Why does Magento split my order into multiple shipments?
Both native algorithms allocate per item rather than solving the whole order, so if no single ranked or nearest source holds every item, the order draws from several sources. The usual fixes are better stock distribution, editing the recommendation, or an algorithm that prefers a single source holding the full order.
Can I write my own source selection algorithm?
Yes. Implement the source selection interface for your Magento version, read the SKUs and address from the inventory request, allocate items across sources by your rule, return the result, and register the class in di.xml under the source selection service with a unique key. Verify the interface name against your version, since it changed across releases.
Does Distance Priority need a Google Maps API key?
Only in Google Maps mode, which calculates real distance and time and bills against your Google usage. Offline mode avoids that by using imported geocode data and country codes, but a developer has to download and import the geocodes through the command line before it works.
Route orders the way your business actually works
Source Selection is one of those systems that is invisible until it ships a two-item order in two boxes from two coasts. Native Magento gives you ranked and distance-based routing and a clean extension point for custom logic. Bemeir is the USA’s first Hyva Gold Partner and an Adobe Commerce shop that builds multi-warehouse fulfillment for real distributors. Learn more about Bemeir and how we model inventory routing that keeps parcels and cost down. See our Hyva development services for the storefront that shows it all accurately.
