Retrieving Magento Sales Order Shipments by Increment ID
Understanding the Magento API Filter System
In Magento, the sales_order_shipmentList method allows you to retrieve shipments using various filters. According to the Magento Definitive Guide, one of these accepted filters is order_increment_id.
However, when trying to use this filter as you’ve described, an error occurs because the order_increment_id column is not directly accessible in the Magento database schema.
Exploring the Underlying Database Structure
The sales_order_shipment table does indeed have a link to the sales_order_increment_id through its parent sales_order entity. The relationship is established via the sales_order_id foreign key. Unfortunately, this relationship isn’t exposed as a direct column filter in the Magento API for security and performance reasons.
An Alternative Approach to Filtering by Increment ID
Since the direct order_increment_id filtering isn’t supported, you can achieve your goal using a two-step process:
- Retrieve the sales_order_id from the sales_order table
Use the salesOrderList API method with a filter for increment_id. This will return an array of orders where each order has its ID.
- Filter shipments by the retrieved sales_order_id
Use your existing salesOrderShipmentList call, but this time use a filter for the order_id, which corresponds to the sales_order_id from step 1.
Example Implementation
Here’s how you can implement this in C#:
// Step 1: Get order data by increment ID
var filters = new Filters();
filters.Add(new ComplexFilter("increment_id", ComplexOperator.Eq, orderIncrementId.ToString()));
var orders = apiService.salesOrderList(sessionId, filters);
int orderId = int.Parse(orders.data[0].resource.order_id);
// Step 2: Get shipments by the retrieved order ID
filters = new Filters();
filters.Add(new ComplexFilter("order_id", ComplexOperator.Eq, orderId.ToString()));
var shipments = apiService.salesOrderShipmentList(sessionId, filters);
In this example:
sessionIdis your current admin session ID.orderIncrementIdis the increment ID of the order you’re interested in.
Conclusion
While Magento’s API documentation suggests that filtering by order_increment_id for shipments is supported, there is currently no direct way to do this due to database schema design and security considerations. The two-step approach described above provides a practical workaround to achieve your goal without needing to modify the core Magento API or database.
Remember to always ensure your API calls are performed within an active admin session for proper authentication. For more information on handling sessions in the Magento API, check out our guide here.
Happy coding!