Stock and Source Configuration design

Table of Contents

• CQRS in Source and Stock APIs
• Inventory Options
• Programming Interface Query API
• Programming Interface Command API

CQRS in Source and Stock APIs for Configuration

The main technical concept we follow in MSI architecture is to segregate Command and Query APIs. In our case, the role of Query APIs play StockItem related interfaces and services as the StockItem entity is an aggregated indexed data among the physical locations (Sources)plus additional business rules on top of it, so that StockItem data is calculated based on the raw data we have on Source level. A customer working with front-end does not update StockItem data directly, he just exposes commands which would be processed by the system later (the role of such commands play Reservation mechanism). This concept has been used for Quantity and Salability status calculation, that's why Magento front-end which works only with Stock Services (i.e. IsProductSalableInterface, IsProductSalableForRequestedQtyInterface, GetProductSalableQtyInterface) is agnostic to the fact whether Magento is Single or Multi-Source under the hood, and the number of sources from which given Stock consists of don't affect the system performance, as the reservation we place at the time of Checkout created on the level of Stock. In contrary to this, an Admin workin in Magento Admin panel updates data on the level of SourceItem which would lead to re-building the StockItem data index. You can get more details about this concept from [CQRS and EventSourcing webinar] video recording (https://www.youtube.com/watch?v=K1jLOiIXL2M).

The similar principle should be applied for StockItem configuration as well so that Front-end would work with StockItem configuration only which is built based on SourceItem configuration. But the things here are a bit more complicated than in comparison to stock availability and salable quantity calculation because there are different configuration options and some of them could be specified on the level of Source, others on the level of Stock. Thus, the process of Indexation and Aggregation data for StockItemConfiguration indexes would be more sophisticated as it should apply own corresponding business rules to build and store each particular Config Option.

Here is a list of all Stock/Source configuration options.

Inventory Options

You can modify global and product specific inventory options through the following locations in the Magento Admin:

• Inventory page in the Stores > Configuration settings
• Sources section > Assigned Sources grid when editing a product in Catalog > Products
• Advanced Inventory page when editing a product

The following table provides information on all product options and configurations, including MSI information. For additional information, see the Magento User Guide, MSI Global Settings.

Name	Product Option	Config Option	Scope	Applied To	Description
Manage Stock	Y	Y	Global	Stock	Sets if inventory control is used for this product or all products in Magento. Displays more options if set to Yes.
Only X left Threshold	Y	Y	Global	Stock	Sets a quantity amount to notify when a specific amount is left available for purchase. This amount is tracked at the stock level.
Out-of-Stock Threshold	Y	Y	Global	Stock	Quantity to trigger an "out of stock" notification.
Minimum Qty Allowed in Shopping Cart	Y	Y	Global	Stock	Sets the minimum quantity of the product that can be purchased in a single order.
Maximum Qty Allowed in Shopping Cart	Y	Y	Global	Stock	Sets the maximum quantity of the product that can be purchased in a single order.
Qty Uses Decimals	Y	N	Global	Source	Allows decimal amounts, instead of whole numbers, for the quantity of a product. This is helpful for products sold by weight, volume, or length. Specified on the level of Source, calculated on the Stock level based on assigned Sources
Allow Multiple Boxes for Shipping	Y	N	Global	Stock	Sets if parts of a product can be shipped separately.
Backorders	Y	Y	Global	Source	Indicates if Backorders are allowed. The available options include: No Backorders, Allow Qty Below 0, or Allow Qty Below 0 and Notify Customer. Specified on the level of Source, calculated on the Stock level based on assigned Sources
Notify for Quantity Below	Y	Y	Global	Source	Sets the quantity that triggers a Quantity Below notification, warning of low stock. This setting is overriden by settings in the Assigned Sources grid.
Enable Qty Increments	Y	Y	Global	Stock	Sets if the product can be sold in quantity increments. If enabled, enter the quantity of products that must be purchased in an incremental step.
Automatically Return Credit Memo Item to Stock	N	Y	Global	Stock	The system handles stock returns automatically.

Programming Interface Query API

It's proposed to remove all the command methods which alter Stock Configuration data out of StockItemConfigurationInterface and make it pure immutable, representing the indexed and aggregated data.

namespace Magento\InventoryConfigurationApi\Api\Data;

/**
 * @api
 */
interface StockItemConfigurationInterface
{
    const BACKORDERS_NO = 0;
    const BACKORDERS_YES_NONOTIFY = 1;
    const BACKORDERS_YES_NOTIFY = 2;

    const IS_QTY_DECIMAL = 'is_qty_decimal';
    const SHOW_DEFAULT_NOTIFICATION_MESSAGE = 'show_default_notification_message';

    /*
     * Safety stock threshold
     */
    const MIN_QTY = 'min_qty';

    /*
     * Threshold intended to show the "Only X left"
     */
    const STOCK_THRESHOLD_QTY = 'stock_threshold_qty';

    /*
     * Used to prevent to buy less than a certain qty of a product, not to confuse with the safety stock threshold
     */
    const MIN_SALE_QTY = 'min_sale_qty';

    const MAX_SALE_QTY = 'max_sale_qty';
    const BACKORDERS = 'backorders';
    const NOTIFY_STOCK_QTY = 'notify_stock_qty';
    const QTY_INCREMENTS = 'qty_increments';
    const ENABLE_QTY_INCREMENTS = 'enable_qty_increments';
    const MANAGE_STOCK = 'manage_stock';
    const LOW_STOCK_DATE = 'low_stock_date';
    const IS_DECIMAL_DIVIDED = 'is_decimal_divided';
    const STOCK_STATUS_CHANGED_AUTO = 'stock_status_changed_auto';

    /**
     * @return bool
     */
    public function isQtyDecimal(): bool;

    /**
     * @return bool
     */
    public function isShowDefaultNotificationMessage(): bool;

    /**
     * @return float
     */
    public function getMinQty(): float;

    /**
     * @return float
     */
    public function getMinSaleQty(): float;

    /**
     * @return float
     */
    public function getMaxSaleQty(): float;

    /**
     * @return bool
     */
    public function isUseConfigBackorders(): bool;

    /**
     * Retrieve backorders status
     *
     * @return int
     */
    public function getBackorders(): int;

    /**
     * @return float
     */
    public function getNotifyStockQty(): float;

    /**
     * Retrieve Quantity Increments data wrapper
     *
     * @return float
     */
    public function getQtyIncrements(): float;

    /**
     * @return bool
     */
    public function isEnableQtyIncrements(): bool;

    /**
     * @return bool
     */
    public function isManageStock(): bool;

    /**
     * @return string
     */
    public function getLowStockDate(): string;

    /**
     * @return bool
     */
    public function isDecimalDivided(): bool;

    /**
     * @return int
     */
    public function getStockStatusChangedAuto(): bool;

    /**
     * @return float
     */
    public function getStockThresholdQty(): float;
}

Programming Interface Command API

Command APIs should be represented as a set of Interfaces corresponding each particular command modifying or retrieving data for given the particular Configuration value.

Command Interfaces for Configuration option Specified on the level of SourceItem

Backorders are a good example of configuration option which supposed to be specified on the Source level (i.e. warehouse), and based on the Sources assigned to given Stock, the configuration value of StockItemConfiguration should be calculated. For example, there are next Sources:

• Source A (backorders = 0)
• Source B (backorders = 0)
• Source C (backorders = 1, Allow Qty Below 0) All of these sources are assigned to Stock A Backorder Stock configuration should be calculated based on SourceItemConfiguration values. In this case calculated value supposed to be backorders = 1.

//Command API for Backorder to set Backorder and retrieve backorder on the level of SourceItem

/**
 * @api
 */
interface SetBackorderStatusInterface
{
    /**
     * @param string $sku
     * @param string $sourceCode Backorder is specified on the level of SourceItem and calculated on the level of Stock
     * @param int $backorderStatus
     * @return void
     */
    public function execute(string $sku, string $sourceCode, int $backorderStatus): void;
}

/**
 * @api
 */
interface GetBackorderStatusInterface
{
    /**
     * @param string $sku
     * @param string $sourceCode Backorder is specified on the level of SourceItem and calculated on the level of Stock
     * @return int
     */
    public function execute(string $sku, string $sourceCode): int;
}

Command Interfaces for Configuration option Specified on the level of StockItem