OMS Connector Integration Architecture

This integration diagram shows a high-level overview of how the Connector integrates Magento Commerce and Order Management.

MC to OMS connection diagram


Catalog Module

Keeps product updates in sync with the Magento OMS

Inventory Module

Keeps inventory stock updates in sync with the Magento OMS

Sales Module

Send new orders, order updates and shipment updates to the Magento OMS

Post Sales Module

Manages returns and refunds

Standard MC functionalities disabled/modified by the MCOM connector

Disabled functionalities

The out of the box Magento provides an implementation of order management and inventory management tools, which may conflict with implementations of the Magento OMS. To avoid it, and stick to “single data storage” concept, some of Magento features are disabled or switched to Read-Only mode.

  • Order management – After an order is sent to OMS no order status changes will be processed by Magento Commerce. All changes will be initiated from the OMS.
  • Inventory management – You should not be able to change product quantity and stock status through the backoffice. Stock status and product quantities are fully controlled by the OMS. For development and testing environment, it will be possible to edit the stock manually in the admin panel in case the developer mode is switched on. In case your catalog contains virtual products that don’t require stock management you can configure the product to have Stock Management disabled in MC Admin.
  • Shipping and Payments methods – Shipping methods will synchronize automatically with your OMS via the magento.catalog.product_management.updated message. Then, the shipping method is created as a SKU in your OMS catalog. For more information, check the Synchronize shipping methods page.

Modified functionalities

  • The default stock values are ignored. All stock information is taken from the newly created stock aggregates (stores > Stock Aggregates). In the product page to see the correct stock information, you will have to select the correct store view.
  • The quantity information displayed in the product grid is taken from the first stock aggregated found. Upon filtering the store view, the quantity will reflect the values from the associated aggregate to the store.
  • The order cancellation will first request the OMS to validate if the order is cancellable, cancel it in the OME and update the new canceled status in MC to ensure the status of the order is consistent across both systems.
  • There is a new button visible in the product grid page “export full catalog” which will export the entire catalog to the OMS.

Integration points

The following integration points and areas have been implemented using the Shared Services approach/infrastructure.

Catalog integration point

Magento or a PIM system, as a catalog provider, should send generic product information to OMS - SKU, Name and basic pricing. The product information is need to validate information for the imported orders. Therefore if an order includes a sku that don’t exist in the OMS catalog, the order will be rejected. By default, the connector will export a new product message or product update to the OMS. Every time there is a product update for any of the fields existing in your OMS catalog, a new message magento.catalog.product_management.updated is sent to your OMS. Catalogs that are imported via csv will be exported in batches of 5000 messages to the OMS, therefore there might be a delay in seeing the products created in the OMS system.

In MC admin panel is also possible to trigger a full catalog export from the Products > Catalog that might be useful to initiate a first synchronization after the full catalog import (this process is not ment to be used for regular updates).


Product custom attributes

It is possible to define from MC admin panel which are the custom attributes for each product that should be exported to OMS. Order custom attributes

Inventory integration point

Magento should support multiple stocks, to be able to use different stock aggregates on different websites. One Magento website can be assigned only to one stock aggregate, but one stock aggregate can be used by few websites. The OMS is responsible for aggregating and calculating stock information for each Magento stock.

Diagram Stock aggregates

A new page is available in MC Admin to configure the stock aggregates under MCOM > Manage Stock Aggregate

Stock aggregates interfaces

Every time a new stock update is sent from OM to MC the quantity for each SKU will be, first reset to zero and then updated with the values provided in the message (therefore if an SKU was not present in the message will be automatically set to zero and Out of Stock).

The connector will also update the “Stock Status” field as follows: if the quantity > 0 the status will be “in Stock” (therefore the product will be visible in the frontend), if quantity <= 0 the status will be set to Out of Stock (therefore the product will disappear from the website). In case any of the products have been configured in OM to have “unlimited” stock, then upon the message reception, MC will update the Manage Stock field to No. Note that in case the “unlimited” stock is not provided for an SKU that already have been set before for “unlimited” the Manage Stock flag will remain set to No.

Advanced Inventory in MC

Order integration point

Magento will prepare and send all authorized orders to OMS (by default all orders with status Pending are exported asynchronously). Is it possible via a configuration to define specific order statuses that should be exported to OMS in case there is a custom order flow that needs to make several checks to ensure the order is correctly authorized. Order status export

The OMS will notify Magento about order status changes via Order Status Update message. In order to export correctly a new order from MC to OMS the MC needs to configure the following in each website:

  • Stores > Configuration > MCOM CONNECTOR > General > Store ID: Store External Id in OMS

Order status update integration point

By default, the MCOM connector will create and map new order statuses in MC as described in the table below. The OMS will notify Magento about order status order orderLine status changes via Order Status Update message. Magento orders have two attributes which indicate the status of the order:

  • state - is used to determine “order phase”, one state may have few statuses. The state is not configurable.
  • status - is used for display information about order status and is it configurable in Admin (new statuses can be added).

Every time that Order changes status a message of Order Updated is sent through the bus. Magento 2 will consume the message and set the new status for the order. If the status does not exist in Magento 2, it will be created. So basically any status that the OMS will send, it will be accepted in Magento 2.

Return integration point

Customer Service can create return request through the Admin interface that will generate a return in status REQUESTED. Once the warehouse receives the parcel and confirms the reception, the OMS will update the status to ACCEPTED upon receiving the return-new feed.

Then customer service agent will be able to see the refund status both in MC and OMS.

Return Integration

In MC there is a configuration that displays the return link in the menu of each order so you can see directly the returns associated with each order. The configuration is found at Stores > Configuration > SALES > Sales > RMA Settings > Enable RMA on Storefront, then set it to Yes.

The usage of this MC return flow is not compatible with the MOM return flow. Please Activate it only in the case that you will extend the MC behaviour to create the returns with MOM specification. In 2018 Q3 this will added in the MOM connector as out of the box feature.

Refund integration point

Refunds are created/managed by the OMS. A message will inform MC of the refund amount and status of the actual refund (Credit Memo). In MC the total on the order summary page will be recalculated to display the refunded amount.

Return Integration


Stock updates

OMS will inform MC of stock quantities every time there is new information available to be exported. For the stock inventory updates, it is needed to ensure that the messages are consumed in the correct order to avoid having values been overwritten inconsistently. CASE: OMS sends a FULL snapshot and a few minutes afterward generated a DELTA update. It is needed to ensure MC is not processing the DELTA update before the FULL is completed so that quantities are not overwritten

  • In the messages sent to M2 for stock updates (Full/Delta) it is included a ‘timestamp’ field.
  • MC have a filter for stock messages as follows:

When a new stockUpdateMessage is consumed:

  • Get the productId and timestamp from message
  • Retrieve corresponding product entry from cataloginventory_stock_item_update
  • If message.timestamp < entry.timestamp then discard message
  • Else, update entry with the message.timestamp and continue stockUpdate process

The solution is to calculate the timestamp for the full import when it is started and use it for all the full messages (like a transaction Id), then the delta will have a higher timestamp than the full, so when the SKU x in the full tries to be updated the message will be discarded because its timestamp is lower than the last update (delta).

Bundle configurations

A bundle is an offering of several products for sale as one combined product. See our Bundles page for more info about bundles and how they work.

In order to correctly process bundles, the connector must correctly map the bundle and its child lines during the creation of the order, so that the bundle is correctly handled. When creating the magento.sales.order_management.create specification in Magento Commerce, the following is validated:

  • The bundle line is of the type BUNDLE.
  • The SKUs inside the bundle have PHYSICAL or VIRTUAL types.
  • the SKUs (options) inside the bundle contain the parent_line_number field, which indicates the line number of the parent bundle.
  • The prices for the SKUs are exported inside the bundle and the price of the bundle line is 0.
  • The shipment method is provided at the bundle line as a custom attribute. So, if all lines are shipped, the bundle is considered to be shipped.


    "order": {
        "id": "123456",
         "lines": [
            "line_number": "1",
            "id": "23",
            "type": "BUNDLE",
            "name": "The Beatles Collection"
            "custom_attributes": [
                    "name": "mom_srcrr_FilterSourceBundleFromOneSource",
                    "value": "SHIPTOGETHER"
            "line_number": "2",
            "type": "SIMPLE",
            "name": "Tee-Shirt Abbey Road",
            "parent_line_id": "23"
            "line_number": "3",
            "type": "VIRTUAL",
            "name": "Magical History Tour Ticket",
            "parent_line_id": "23"

The parent_line_id is referencing the line ID, not the line number, to ensure that the identifier is correctly mapped in Magento Commerce, as Magento Commerce does not identify line_numbers that are created by the connector.

When stock is available for all children lines, the bundle is visible in your Magento Commerce implementation.

For more information, see the Bundles page.