Source Selection Algorithms

Overview

Multiple Sources Inventory (MSI) implies that the products will be stored in multiple locations. When Customer buys the product, it should be shipped from the particular location. A customer usually does not care what location product was shipped from, as soon as this is the cheapest option. For the Merchant, it is important to have minimal overhead for the inventory storage and shipping costs. An algorithm which assigns the particular inventory to the order item should take all these considerations into account and select the best possible options.

When multiple carriers and/or sources are used for delivery, there will be multiple possible shipping combinations that can fulfill the order. Merchants need to be able to present a consolidated shipping amount to the customer but need to be able to control which combination is selected. The merchant needs the ability to configure how the shipping amount is calculated in these scenarios, so they can choose the calculation algorithm that best matches their preferences.

Thesaurus

• Source - synonyms which are used to identify a single location of the inventory storage which has the physical address. The merchant may have multiple of those when using multi-source inventory.
• Source selection algorithm - an algorithm which decides which source of the inventory should be used to fulfill the order.

Use-Case

To visualize the process of the source selection let's describe the following use-case. Customers create an Order to buy products A, B and C:

Product	Qty
A	10
B	2
C	7

Merchant has following stock quantities in sources X, Y and Z

Product	Source	Qty
A	X	10
A	Y	10
A	Z	10
B	X	1
B	Y	1
B	Z	1
C	X	5
C	Y	2
C	Z	7

There are multiple possible options on how to fulfill the order:

1. Ship 10xA from the Source X, 1xB from the X and 1xB from Z, 5xC from the X and 2xC from Y
2. Ship 5xA from X and 5xA from Y, 1xB from the X and 1xB from Z, 7xC from the Z
3. etc

As you can see there are multiple possible strategies on how to optimize order fulfillment:

• Try to ship as much as possible from one source. This minimizes packaging costs and possibly shipping cost
• Try to distribute the load between sources. This minimizes storage cost
• select source based on the cost of shipment to the merchant address for the particular Carrier
• select source based on the shipment time

The order fulfillment algorithm should pick the location of the product and use it to calculate the shipping cost.

Problem

Earlier implementations of MSI identified the problems with the advanced algorithms of the source selection. For example, if the source selected based on the delivery cost, for every possible combination of sources system should perform the API call to the carrier to retrieve the shipping cost.

Approach

It is impossible for the Magento platform to predict all the circumstances which affect inventory and shipping costs for the particular merchant. That's why instead of implementing all possible optimizations of the source selection algorithm, the framework will contain the interface which is used to resolve the Source for the order item. Different implementations of the algorithm will contain Implementations, provided by the 3-d party extensions will allow affecting the priorities of the source selection depending on the particular case where Magento is used.

Magento framework will provide the default, rule-based algorithm which allows configuring the priority of sources depending on the source origin, shipping address and the selected carrier.

Interfaces

Following interface will be called by the Magento framework at the point of shipment calculation. Changing the implementation of the interface allows affecting the algorithm of the Source resolution.

use Magento\Quote\Model\Quote\Address\RateRequest;

/**
 * SourceShippingResolverInterface
 */
interface SourceResolverInterface
{
    /**
     * Resolve source shipping data
     *
     * @param RateRequest $request
     * @param ShippingRateCalculator $shippingRateCalculator
     * @return array
     */
    public function resolve(RateRequest $request, ShippingRateCalculator $shippingRateCalculator);
}

Default Algorithms

By Priority

Algorithm steps:

1. Get list of sources sorted by priority (source attribute)
2. Take all available products from 1st source by priority. If some of the products in the order couldn't be delivered from the 1st source - get the rest of products from next by priority source.
3. Repeat Step 2. until all the products from the order would be ready to shipping.

By Minimal Delivery Cost:

Algorithm steps:

Delivery to fulfill the order could be made from one or several (more than one) sources

1. Evaluate each source for one product delivery
2. Fulfill the order by minimal cost sources (result is sum of each value)
3. Recalculate Shipping cost based on previous step result. Obtained value is displayed for the customer.

Example 1. Each product item delivered from a single Source:

Shopping Cart:

Product	Qty
A	2
B	2

Sources Inventory:

Product	Source	Qty
A	X (Flat Rate - 10$)	100
A	Y (Flat Rate - 10$)	100
B	X (Flat Rate - 15$)	100
B	Y (Flat Rate - 15$)	100

Algorithm steps:

1. Collect all common sources (with delivery cost) for all products in shopping cart
   • 2xA from X, 2xB from X = 10$
   • 2xA from Y, 2xB from Y = 15$
2. We choose first combination with minimal cost
   • 2xA from X, 2xB from X = 10$

Example 2. delivery made from several Sources:

Shopping Cart:

Product	Qty
A	2
B	2

Sources Inventory:

Product	Source	Qty
A	X (Flat Rate - 10$)	100
A	Y (Flat Rate - 10$)	1
B	X (Flat Rate - 15$)	100
B	Y (Flat Rate - 15$)	1

Algorithm steps:

1. Collect one product delivery cost for each source:
   • (a) 1 Product A from Source X = 10$
   • (b) 1 Product A from Source Y = 15$
   • (c) 1 Product B from Source X = 10$
   • (d) 1 Product B from Source Y = 15$
2. Fulfill the order by minimal cost sources:
   • (2 * a) + (1 * c) + (1 * d)
3. Recalculation:
   • We can see that we have two products going to be delivered from single stock, but we used Flat Rate cost twice. So we need to repeat calculation based on result from prev step: 25$ (this value is displayed for customer)

Example 3 without common Source (more complexity):

Shopping Cart:

Product	Qty
A	2
B	3
C	4

Sources Inventory:

Product	Source	Qty
A	X	100
A	Y	100
B	X	2
B	Y	2
C	X	2
C	Y	2

Algorithm steps:

1. Collect one product delivery cost for each source:
   • (a) 1 Product A from Source 1 = 10$
   • (b) 1 Product A from Source 2 = 15$
   • (c) 1 Product B from Source 1 = 10$
   • (d) 1 Product B from Source 2 = 15$
   • (e) 1 Product C from Source 1 = 10$
   • (f) 1 Product C from Source 2 = 15$
2. Fulfill the order by minimal cost sources:
   • (2 * a) // Product A is fulfill
   • (2 * c) + (1 * d)
   • (2 * c) + (1 * d) // Product B is fulfill
   • (2 * e) + (2 * f) // Product C is fulfill
3. Recalculation
   • We can see that we have two products going to be delivered from single stock, but we used Flat Rate cost twice. So we need to repeat calculation based on result from prev step: 25$ (this value is display for customer)

Delivery Cost Configuration

To support Minimal Delivery Cost algorithm, Magento should have some source of information about the shipping prices. This information can be statically stored in the database. The source of information can be either import file or admin UI or background job which caches the shipping combinations. However, by default, just import from CSV should be supported.

Magento will allow creating rules of selecting the fulfillment source based on following pieces of information:

• source addresses
• customer shipping address
• carrier

The rules will be defined in the format: ``(Customer State, Carrier) -> Source.'' By default, Magento will provide the way to import the rules will be configured in the CSV file.

Acceptance Criteria

Following are the Acceptance Criteria for the Source Selection Algorithm.

1. There is an interface of the Source Selection which can be implemented by the extension to provide the logic of the source selection
2. The interface is used by the Magento framework during the shipping rate calculation. Shipping rate calculation which uses the interface:
   1. is compatible with bundle products
   2. is compatible with configurable products
   3. is compatible with backorders
   4. is compatible with multi-address shipping
3. Information about selected source reflected on the Order and be available during the fulfillment:
   1. Merchant views and modifies sources selected for delivery after order is placed before shipment is created
   2. Merchant views relevant source data for all shipments from the order shipments list and detail page for each shipment
   3. Merchant defines which sources are used for fulfillment for each website
4. There are default implementations of the source selection interface via base source selection algorithms
   1. By Priority
   2. By Minimal Delivery Cost. Uses proximity sorting for improved performance (proxy minimal cost option)
5. Magento allows to perform Delivery Cost Configuration used by the Minimal Delivery Cost algorithm
   1. Delivery costs for different source locations, different destinations and different carriers are stored in the database
   2. Delivery costs can be imported via CSV File