How to properly add a shipping_description column in magento order grid?

How to properly add a shipping_description column in magento order grid?

October 14, 2026 · Illustrated author avatarBy Stefan Bogdanescu
How to properly add a shipping_description column in magento order grid?

Resolving “Shipping Description” Column Sorting Issues in Magento Grid

Sorting issues are common when adding new columns like ‘shipping_description’ to the Magento order grid. The error messages you encountered - “Column ‘status’…is ambiguous” or “Column ‘increment_id’…is ambiguous” - indicate that the database engine is confused about which table to use for the sort operation.

Let’s dive into the root cause and provide a step-by-step solution to properly add the shipping_description column and resolve the sorting issues in Magento 2.x.

Understanding the Issue: Ambiguous Column References

The error occurs because when you join multiple tables, the database engine doesn’t know which table’s column to use for sorting unless explicitly specified. In your case, both ‘status’ and ‘increment_id’ columns exist in the sales_flat_order_details table (used by Grid.php) as well as the sales_flat_orders table.

Solution: Explicitly Specify Table Prefixes

To resolve this ambiguity, you need to prefix column names with their respective table names. This tells the database engine exactly which table’s column to use for sorting operations. Here’s how to modify your code:

protected function _prepareCollection()
{
    $collection = Mage::getResourceModel($this->getCollectionClass());

    $tableName = Mage::getSingleton("core/resource")->getTableName('sales_flat_order');
    $collection->getSelect()->joinLeft(
        array('order_details' => $tableName),
        "main_table.entity_id = order_details.parent_id",
        array('shipping_description')
    );
    $this->setCollection($collection);
    return parent::_prepareCollection();
}

And for the columns:

protected function _prepareColumns()
{
    $this->addColumnAfter(
        'shipping_description',
        array(
            'header' => Mage::helper('sales')->__('Shipping Description'),
            'width' => '180px',
            'type' => 'text',
            'index' => 'order_details.shipping_description'
        ),
        'shipping_name'
    );

    return parent::_prepareColumns();
}

Key Changes Made

  • Changed the join to a left join with joinLeft method.
  • Specified an alias for the sales_flat_order table as ‘order_details’.
  • Prefixed the column name with the alias in the array: 'index' => 'order_details.shipping_description'.

These changes ensure that when you sort by shipping description, the database engine knows exactly which table’s column to use.

Conclusion

Sorting issues in Magento order grid can be challenging but are resolvable with the right approach. By properly prefixing column names and using explicit joins, we can eliminate the ambiguous column reference errors and enable sorting by custom columns like ‘shipping_description’.

Remember, while this solution works for Magento 2.x, the exact implementation may vary based on your specific version or configuration. Always test changes thoroughly in a development environment before deploying to production.

For more advanced customization techniques, I recommend checking out our comprehensive guide on Extending the Magento Order Grid for a deeper dive into customizing and extending the order management system.

Happy coding!

Magento 2 Database Themes Admin

Our network