Properly add new columns to sales order grid in Magento 2

Properly add new columns to sales order grid in Magento 2

August 2, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Properly add new columns to sales order grid in Magento 2

Properly Add New Columns to Sales Order Grid in Magento 2

Adding new columns to the sales order grid in Magento 2 involves several steps that require careful configuration of your module’s resources, data provider, and UI components. A common issue you might encounter is an error related to ambiguous column names or duplicate IDs when trying to filter orders by ID.

Let me walk you through a step-by-step solution based on the provided code snippets and errors:

Understanding the Error

The first error occurs because the collection already contains a document with the same ID. This happens due to the way Magento handles UI component data providers. The second error is an integrity constraint violation, indicating that the database is ambiguous about which ‘created_at’ column to use.

Correcting Your Collection Class

In your Vendor/Module/Model/ResourceModel/Order/Grid/Collection.php file, you need to ensure that all joins are handled correctly and that the filters are properly mapped. Here’s an updated version of your collection class:

namespace Wetag\AdditionalOrderFields\Model\ResourceModel\Order\Grid;

use Magento\Framework\Data\Collection\Db\FetchStrategyInterface as FetchStrategy;
use Magento\Framework\Data\Collection\EntityFactoryInterface as EntityFactory;
use Magento\Framework\Event\ManagerInterface as EventManager;
use Magento\Sales\Model\ResourceModel\Order\Grid\Collection as OriginalCollection;
use Psr\Log\LoggerInterface as Logger;

/**
 * Order grid extended collection
 */
class Collection extends OriginalCollection
{
    protected $helper;

    public function __construct(
        EntityFactory $entityFactory,
        Logger $logger,
        FetchStrategy $fetchStrategy,
        EventManager $eventManager,
        $mainTable = 'sales_order_grid',
        $resourceModel = \Magento\Sales\Model\ResourceModel\Order::class
    )
    {
        parent::__construct($entityFactory, $logger, $fetchStrategy, $eventManager, $mainTable, $resourceModel);
    }

    protected function _renderFiltersBefore()
    {
        $joinTable = $this->getTable('sales_order');
        $joinTable_track = $this->getTable('sales_shipment_track');

        // Join the main order table
        $this->getSelect()->joinLeft($joinTable, 'main_table.entity_id = sales_order.entity_id', ['shipping_information'])->group('main_table.entity_id');

        // Join the shipment track table
        $this->getSelect()->joinLeft($joinTable_track, 'sales_order.entity_id = sales_shipment_track.order_id', ['track_number'])->group('sales_shipment_track.order_id');

        parent::_renderFiltersBefore();
    }

    protected function _initSelect()
    {
        $this->addFilterToMap('increment_id', 'main_table.increment_id');
        $this->addFilterToMap('status', 'main_table.status');
        parent::_initSelect();

        return $this;
    }
}

Key Changes Made

  1. I’ve added the group() function after each join to ensure that the query groups by the corresponding primary key of the joined tables.

  2. I’ve removed the line causing the ambiguity issue: $this->getSelect()->joinLeft($joinTable, 'main_table.entity_id = sales_order.entity_id', ['shipping_information'])->distinct();

Additional Configuration Steps

Step 1: Update your di.xml file

Ensure that your di.xml file in Vendor/Module/etc/di.xml contains the following:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\Framework\View\Element\UiComponent\DataProvider\CollectionFactory">
        <arguments>
            <argument name="collections" xsi:type="array">
                <item name="sales_order_grid_data_source" xsi:type="string">Vendor\Module\Model\ResourceModel\Order\Grid\Collection</item>
            </argument>
        </arguments>
    </type>
    <type name="Vendor\Module\Model\ResourceModel\Order\Grid\Collection">
        <arguments>
            <argument name="mainTable" xsi:type="string">sales_order_grid</argument>
            <argument name="resourceModel" xsi:type="string">Magento\Sales\Model\ResourceModel\Order</argument>
        </arguments>
    </type>
</config>

Step 2: Update your module.xml file

Ensure that the sequence tag in your etc/module.xml file includes the necessary dependencies:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../lib/internal/Magento/Framework/Module/etc/module.xsd">
    <module name="Vendor_Module" setup_version="1.0.0">
        <sequence>
            <module name="Magento_sales"/>
        </sequence>
    </module>
</config>

Step 3: Update your sales_order_grid.xml file

Ensure that the UI component definition in your Vendor/Module/view/adminhtml/ui_component/sales_order_grid.xml is correctly configured:

<?xml version="1.0" encoding="UTF-8"?>
<listing xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
    <columns name="sales_order_columns">

        <column name="shipping_information">
            <argument name="data" xsi:type="array">
                <item name="config" xsi:type="array">
                    <item name="filter" xsi:type="string">text</item>
                    <item name="label" xsi:type="string" translate="true">Shipping method</item>
                </item>
            </argument>
        </column>

        <column name="track_number">
            <argument name="data" xsi:type="array">
                <item name="config" xsi:type="array">
                    <item name="filter" xsi:type="string">text</item>
                    <item name="label" xsi:type="string" translate="true">Tracking number</item>
                </item>
            </argument>
        </column>

    </columns>
</listing>

Conclusion

Adding new columns to the sales order grid in Magento 2 involves a careful configuration of your module’s resources, data provider, and UI components. By properly joining the necessary tables, mapping filters correctly, and ensuring that dependencies are set up appropriately, you can avoid the errors discussed earlier.

Remember, when adding custom columns, it’s crucial to ensure that the joins are handled correctly to prevent ambiguous column names or duplicate IDs from causing issues during filtering.

If you’re looking for more advanced solutions or professional Magento development services, feel free to explore our offerings at Laravel Company.

Happy coding!

Magento 2 Database Extensions Admin

Our network