README

Conneqt_Base is the foundation module for the Conneqt Magento 2 integration.

In short, it adds a custom order import API and a set of Magento plugins, observers, and overrides that make Magento behave better when data is being synchronized from an external system. The module mainly focuses on:

• importing orders through a custom REST endpoint
• handling bundled product selections on imported order items
• adjusting customer and address updates for integration use cases
• controlling inventory reservation and source deduction behavior
• customizing product URL key and product update behavior

What this module does

The module introduces a custom REST endpoint at POST /V1/conneqt_orders. That endpoint accepts an order payload and turns it into a Magento order by:

1. creating or reusing a customer quote
2. adding the incoming order items to the quote
3. mapping bundled product selections to Magento bundle options
4. filling billing and shipping addresses
5. applying payment and shipping information
6. placing the Magento order
7. restoring totals and item prices from the external payload
8. optionally linking the new order to an older Magento order when the payload represents an edit/replacement flow

Besides order import, the module also changes a few default Magento behaviors to better support external synchronization.

How it works

1. Custom order API

The main integration entry point is defined in:

• etc/webapi.xml
• Api/OrderInterface.php
• Model/Api/Order.php

etc/webapi.xml exposes Conneqt\Base\Api\OrderInterface::placeOrder() as:

• POST /V1/conneqt_orders

Model/Api/Order.php contains the actual order import workflow. It rebuilds the quote from the incoming order data, places the order, updates totals and line item amounts, and sends the order email at the end.

2. Extension attributes for imported order data

The module extends Magento order data with custom attributes in:

• etc/extension_attributes.xml
• Api/Data/BundledOptionInterface.php
• Api/Data/BundledOptionSelectionInterface.php
• Model/BundledOption.php
• Model/BundledOptionSelection.php

These files let order items carry conneqt_bundled_options, so imported bundle products can be mapped to Magento's internal bundle option structure before the quote is placed.

3. Magento behavior overrides for integration requests

The module hooks into Magento through etc/di.xml, etc/webapi_rest/di.xml, and etc/events.xml. These XML files register plugins, preferences, and observers that adjust Magento behavior during API-driven imports and updates.

Important files and what they do

Key integration behaviors

Order import

The order import flow lives in Model/Api/Order.php. A high-level summary:

• A quote is created for the customer from the incoming payload.
• Existing quote items are cleared.
• Incoming order items are added to the quote.
• If bundled options are present, they are translated into Magento bundle option data.
• Billing and shipping addresses are copied from the payload, or loaded from the customer defaults when needed.
• Shipping and payment information are saved.
• Magento places the order.
• The created order is updated with the external totals and item prices.
• If the payload refers to an existing Magento order, the new order is linked to it as an edited/replacement order and the old order is cancelled.

Customer create-to-update fallback

Override/RestOverride.php changes Magento's REST handling for a specific integration case. When customer creation fails because the customer already exists, the module can convert the request into a PUT update request instead of returning the original failure immediately.

This behavior is protected by config and a password field defined in etc/adminhtml/system.xml.

Address matching by external ID

Plugin/ExternalIdAddressUpdate.php allows the integration to update a customer address without sending a Magento address entity ID. If the submitted address contains a matching external_id for the same customer, the plugin loads the existing address and turns the save into an update.

Inventory and reservations

The inventory-related plugins help merchants whose stock is managed partly or fully outside Magento.

• Plugin/SourceItemsSavePlugin.php can clear reservations after stock updates.
• Plugin/InventoryReservationsApi/AllowOnlyOrderPlacedReservationsPlugin.php can limit appended reservations to order_placed events.
• Plugin/SourceDeductionServicePlugin.php can skip source deductions when shipping without stock is allowed.

Product update behavior

The product-related customizations are:

• Plugin/ProductRestApi.php: prevents unwanted attribute set changes through the REST API.
• Model/ProductUrlPathGeneratorOverride.php: changes how URL keys are generated, including optional SKU-based behavior.

Admin configuration

The module adds configuration under:

• Stores > Configuration > CONNEQT > Base

The settings are defined in etc/adminhtml/system.xml. The most important options are:

• reservation cleanup after stock updates
• experimental reservation filtering
• allowing shipment creation without enough stock
• allowing customer updates based on matching email
• allowing customer address updates based on external_id
• SKU-based product URL keys
• allowing or blocking attribute set changes through REST

Default values are defined in etc/config.xml. Currently, allow_attribute_set_change defaults to enabled.

Setup patch

Setup/Patch/Data/AddExternalIdCustomerAddressAttribute.php adds the external_id customer address attribute used by the address matching logic. This attribute is intended for admin customer address forms and supports integration-side address identity mapping.

Where to start when reading the code

If you are new to this module, read the files in this order:

1. etc/webapi.xml
2. Api/OrderInterface.php
3. Model/Api/Order.php
4. etc/di.xml
5. Override/RestOverride.php
6. Plugin/
7. etc/adminhtml/system.xml
8. Setup/Patch/Data/AddExternalIdCustomerAddressAttribute.php

That gives a good overview of both the public API and the Magento behaviors this module customizes.

Module name

• Magento module: Conneqt_Base
• Composer package: conneqt/m2-base