Inventory

This page details the different inventory flows in the Order Management System (OMS), such as an inventory update, a reindex, or an export process.

We retain historical aggregate stock and source stock information for 60 days. Find aggregate stock and source stock history in the OMS Admin—Products > Inventory > Aggregate Stock (and Source Stock) > View in History column.

Update source stock quantities

Your OMS expects to receive on hand stock quantities for each source. The information is exported to the sales channels and new orders are sourced according to stock availability.

There are two ways to update stock:

• Stock-snapshot—Send a single message for a specific source (DELTA, FULL, or NONZERO) for intra-day updates; If you have a very large catalog we recommend sending stock-snapshot updates in batches.
• Adjustment—Frequent intra-day adjustments that adjust the relative stock to the available quantity already in your OMS. Available stock is then recalculated to be sold for the modified SKUs and exported a DELTA stock-snapshot message.

The stock-snapshots can be provided using three different modes:

There is a limitation of 10,000 SKUs per stock update message. If you want to update more than 10K SKUs, we strongly recommend you use Batch mode.

Stock update examples

FULL mode

{
  "snapshot": {
    "source_id": "SOURCE",
    "mode": "FULL",
    "created_on": "2019-06-11T05:39:21+00:00",
    "stock": [
      {
        "sku": "SKU1",
        "quantity": "111"
      },
      {
        "sku": "SKU2",
        "quantity": "222"
      }
    ]
  }
}

NONZERO mode

{
  "snapshot": {
    "source_id": "SOURCE",
    "mode": "NONZERO",
    "created_on": "2019-06-11T05:39:21+00:00",
    "stock": [
      {
        "sku": "ABC",
        "quantity": "5"
      },
      {
        "sku": "ADC",
        "quantity": "63"
      }
    ]
  }
}

DELTA mode

{
  "snapshot": {
    "source_id": "SOURCE2",
    "mode": "DELTA",
    "created_on": "2019-06-11T05:39:21+00:00",
    "stock": [
      {
        "sku": "EFG",
        "quantity": "10"
      },
      {
        "sku": "JKL",
        "quantity": "39"
      }
    ]
  }
}

Batch mode

Batch processes in a stock update allow for better performance (minimal re-index triggering) because the system waits to receive all messages from a batch before launching stock re-aggregation. Any process will be imported at the source stock level as soon as it is received.

There are two main use cases for using batch mode:

• Same source—-For big stock updates (more than 10K SKUs)
• Multiple sources—Used to avoid overloading the frontend, as only one message will be exported at the end of the process (aggregates are linked to multiples sources)

After reindex, the OMS triggers a magento.inventory.aggregate_stock_management.updated message delivered to your frontend.

If all all processes of the batch were not received after a certain amount of time (configurable in the SI Portal, and global to all inventory), the system will automatically complete the batch and launch the reindex. If any missing process arrives to the system afterwards, it will be discarded.

A batch can be used in a FULL or DELTA mode. If using NONZERO mode, and not all processes are received, the system will ZEROFY all SKUs for the source and import only the stock that is actually received. We recommend you do not use batching and NONZERO mode if you want to update more than 10,000 SKUs. Instead, use FULL mode.

The created_on timestamp must be different for every element of the batch.

Batch in FULL mode

{
  "snapshot": {
    "source_id": "SOURCE",
    "mode": "FULL",
    "batch": {
        "process_id": "806a752a-5662-4250-b73b-b76f513eda1c",
        "process_number": 1,
        "process_total": 100
    },
    "created_on": "2019-06-11T05:39:21+00:00",
    "stock": [
      {
        "sku": "SKU1",
        "quantity": "111"
      },
      {
        "sku": "SKU2",
        "quantity": "222"
      }
    ]
  }
}

To determine if a batch in FULL mode is the most recent snapshot and should be processed, only the first message received by the OMS (not always the first process of the batch) will be checked. If the first message is processed, then all the processes of a batch will also be processed independently of the created_on field.

Batch in DELTA mode

{
  "snapshot": {
    "source_id": "SOURCE2",
    "mode": "DELTA",
    "batch": {
        "process_id": "806a752a-5662-4250-b73b-b76f513g5gs",
        "process_number": 1,
        "process_total": 100
    },
    "created_on": "2019-06-11T05:39:25+00:00",
    "stock": [
      {
        "sku": "EFG",
        "quantity": "10"
      },
      {
        "sku": "JKL",
        "quantity": "39"
      }
    ]
  }
}

Stock adjustments

Use the magento.inventory.source_stock_management.adjust message to perform a stock adjustment.

If an adjustment is received before a stock-snapshot it is discarded. A stock-snapshot is the first stock update to be sent to the OMS when creating a new item or item option. This way, the inventory has an absolute quantity. Then an adjustment can be sent.

Stock adjustment

{
  "adjustment": {
    "adjustments": [
      {
        "quantity": -9,
        "sku": "ABC"
      }
    ],
        "created_on": "2019-12-10T20:45:00+00:00",
        "reason": "DAMAGED",
        "source_id": " SOURCE1"
  }
}

Configure stock aggregates

Your OMS has the capability to define stock aggregates, which are entities which define the stock pool that is exported to the sales channel. Multiple stock sources are associated with each aggregate, and can link to one or several sales channels.

Quickly and easily add and configure sources right in the OMS Admin, or via the API.

Via OMS Admin

The following configuration fields are available for individual stock aggregates and sales channels in the OMS Admin.

Stock aggregates and Sales channels section

Safety stock is used to calculate the available quantity to sell (at the aggregate level) and does not take into account available source stock.

To add and configure new stock aggregates via the Admin:

1. Navigate to System > Stock aggregates and Sales channels.
2. Click Add Stock aggregate.
3. Add info for the External ID, Name, Default Safety Stock, Outlet Safety Stock, and End of Life Safety Stock fields.
4. Select a set—one or multiple—of applicable sources that will form the aggregate.

5. Click Create.

   Create new stock aggregate

   

Via the API

To add and configure stock aggregates via the API:

Use the source management create and update messages to create and update stock to be used in the aggregate.

    {
    "source": {
        "id": "string",
        "name": "string",
        "type": "string",
        "timezone": "string",
        "configurations": {
        "active": "boolean",
        "capabilities": {
            "shipping": [
            "string"
            ],
            "services": [
            "string"
            ],
            "accepts_returns": "boolean",
            "fulfillment": {
            "can_ship_to_source": "boolean"
            }
        },
        "integration_name": "string",
        "ship_from_store": "boolean"
        },
        "address": {
        "reference": "string",
        "address_type": "string",
        "first_name": "string",
        "last_name": "string",
        "address1": "string",
        "address2": "string",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country_code": "string",
        "phone": "string",
        "email": "string",
        "latitude": "string",
        "longitude": "string",
        "custom_attributes": [
            {
            "name": "string",
            "value": "string"
            }
        ]
        },
        "aggregate_ids": [
        "string"
        ]
    },
    "user": "string"
    }

Use the stock aggregate management create and update messages to create or update aggregates.

    {
    "aggregate": {
        "id": "string",
        "name": "string",
        "sources": [
        "string"
        ]
    }
    }

Export stock aggregation updates

Every time there is a stock snapshot update from a warehouse or a physical store the re-index process recalculates the real stock available to sell. The process takes into account the following parameters:

• In-flight orders
• Aggregation of the various sources/quantities
• Safety stock calculations (thresholds defined at source or aggregate level)

In the OMS Admin you can export updates for each sale or cancellation event to keep multiple sales channels using the same aggregate, which is updated as soon as new orders are received in your OMS.

We only export aggregated stock when an order item is hard allocated, not soft allocated. The frontend, Magento Commerce (MC), keeps track of in-flights so the OMS does not need to export it (as the quantity is already correct in MC).

Your System Integrator (SI) can change the export mode in your SI Portal. Alternatively, contact Support for assistance.

The inventory export process manages DELTA, NONZERO, and FULL modes differently:

• DELTA mode—The system exports an aggregate updated message in DELTA mode, and only the SKUs present in the stock update message are exported.

For DELTA stock updates with more than 1000 SKUs, or if more than 500 stock updates are received simultaneously, the export will complete in FULL mode.

• NONZERO mode—Only the SKUs present in the stock update message are exported. All SKUs not present in the message will be changed to a quantity of 0.
• FULL mode—All SKUs of the catalog are exported.

Configure sources

Quickly and easily add and configure sources right in the OMS Admin, or via the API. You can configure source nodes, applicable capabilities, and pickup locations all from the same Admin page.

Via OMS Admin

The following configuration fields are available for individual sources in the OMS Admin.

Details section

Capabilities section

Configurations section

Contact section

Address section

Add single sources

To add or configure a single source in the Admin:

1. Navigate to System > Sources.
2. To edit an existing source, click the available source in the Name column, or to create a new source click Add source.

3. In the Details section, add a source Name, an External ID (like “SOU1”), a Type (like “WH”), the Timezone in which the source operates, an Internal ID (an integer, such as “1”), and a Safety Stock number (stock exported as available to sell) in the applicable fields.

   The safety stock can be defined at the source level, but not at the SKU level.

   

4. In the Capabilities section, enable or disable the ability to accept returns, fulfill and ship orders to another source, or use the source for ISPU orders via the applicable fields.
5. In the Configurations section, add an applicable source integration and enable or disable the source for SFS orders.
6. In the Contact section, add a first and last name, email, and contact phone number for the source contact.
7. In the Address section, add the address, including city, state, zip, country, latitude, and longitude, for the source location.
8. Click Update, if you are updating an existing source, or Create, if you are creating a new source.

Add/edit sources in bulk

To make it easier to add or edit sources, you can download a generated .csv file template, add or edit source information, and re-upload it to the OMS Admin:

1. In System > Fulfillment > Sources, click Download CSV.
2. Open the downloaded file and add or edit any of the fields in the spreadsheet, including SOURCE_NAME, IS_PICKUP_LOCATION, ADDRESS, and more.
3. Click Upload CSV, choose the applicable file and click Upload. The information in the uploaded file will update in the Admin, and you will see the new info in the Sources view.

Via the API

You can also use the API to create a new source or edit an existing source.

Use the magento.inventory.source_management create message to create a new source and the update message to update an existing source.

You cannot currently configure safety stock via the API option. That configuration must be modified in the Admin.

  {
    "source": {
      "id": "string",
      "name": "string",
      "type": "string",
      "timezone": "string",
      "configurations": {
        "active": "boolean",
        "capabilities": {
          "shipping": [
            "string"
          ],
          "services": [
            "string"
          ],
          "accepts_returns": "boolean",
          "fulfillment": {
            "can_ship_to_source": "boolean"
          }
        },
        "integration_name": "string",
        "ship_from_store": "boolean"
      },
      "address": {
        "reference": "string",
        "address_type": "string",
        "first_name": "string",
        "last_name": "string",
        "address1": "string",
        "address2": "string",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country_code": "string",
        "phone": "string",
        "email": "string",
        "latitude": "string",
        "longitude": "string",
        "custom_attributes": [
          {
            "name": "string",
            "value": "string"
          }
        ]
      },
      "aggregate_ids": [
        "string"
      ]
    },
    "user": "string"
  }

In-flight stock

In-flight stock is a mechanism to ensure that orders, which are not yet sourced or fulfilled, have a stock reservation in place that prevents other customers from allocating the same SKU on a new order (it sets aside stock so that a new purchase does not grab an item that’s already meant for a previous order).

In your OMS there are two types of in-flight stock:

• Soft in-flights—Set as soon as the order is imported (while pending validations, such as payments, risk assessments, remorse time, or sourcing). This reduces the stock quantity from the aggregate stock pool.
• Hard in-flights—Defined as soon as an order is sourced. The stock is decremented from the source stock quantities until the logistics provider is informed of the acknowledgment of the purchased SKUs.

The soft in-flights are only removed by your OMS when an order gets hard-allocated, and changes the items to hard in-flights. The logistics provided triggers the removal of the in-flight for hard-allocated items by acknowledging the reception of those order lines.

The acknowledgment by the logistics provider is done via the lines_change_status message, and indicates the RECEIVEDBYLOGISTICS status at each order line.

At this point, your OMS assumes that the WMS/Logistics has already accounted for these order items, therefore it expects that the snapshot is already accounting for them, and removes the hard in-flight.

If a logistics provider is not capable of sending the RECEIVEDBYLOGISTICS status to your OMS, the hard in-flight will be accounted for until the lines are either shipped or cancelled.

Email notification for orders to fulfill

Every time a Ship from Store (SFS) order is generated an email is sent to the store assistant to notify them of orders that need to be fulfilled.

This configuration is only available for SFS orders at this time, but we are working to enable this option for ISPU and STS orders as well.

To configure the email sent to store assistants about orders ready to be fulfilled:

1. To enable (make active and visible) the Categories for configuration in your System Integrator (SI) Portal, select a scope from the Select scope dropdown.
2. Navigate to Sales Channel > Omnichannel > SFS email to store assistant.
3. Select to enable the SFS email.
4. Add a standard email subject in the Email Subject field.
5. Add text for the body of the email, in the Email Body field, that will be sent to store assistants.
6. Click Save.

The email recipient is defined at the Source level, via the Email option.

These definitions are enabled and configured in your System Integrator (SI) Portal, which is not yet accessible externally. Contact Magento Support for assistance.