Unlocking Advanced Order Filtering in ESHOPMAN: Addressing `items.fulfilled_quantity` Query Limitations

Unlocking Advanced Order Filtering in ESHOPMAN: Addressing items.fulfilled_quantity Query Limitations

In the world of headless commerce, efficient order management is paramount. ESHOPMAN, as a powerful HubSpot application for storefront management and HubSpot CMS deployment, provides a robust Admin API to interact with your store's data. However, a recent community discussion highlighted a specific challenge when attempting to filter orders using certain detailed fields within the order_item entity, such as fulfilled_quantity.

The Challenge: Unexpected Errors in Order Item Filtering

Developers and merchants leveraging ESHOPMAN's Admin API for precise order management encountered an issue when trying to filter orders based on fields like items.fulfilled_quantity. For instance, a common attempt to query orders where specific items had a certain fulfilled quantity would result in an error message similar to:

Trying to query by not existing property OrderLineItem.fulfilled_quantity

This limitation meant that while the ESHOPMAN public order model clearly exposes detailed fields like quantity, fulfilled_quantity, shipped_quantity, delivered_quantity, and others on the order_item join entity, the filtering mechanism wasn't correctly recognizing them.

Understanding the ESHOPMAN Internal Logic

The root cause of this behavior lies within ESHOPMAN's internal order module processing. Specifically, when filters are applied to order items, the system performs a remapping of these filters into its repository shape. While the public ESHOPMAN order model presents items as the comprehensive order_item join entity, the internal remapping logic was inadvertently limiting which fields were correctly routed for filtering.

Initially, only a select few fields—quantity, unit_price, and compare_at_unit_price—were properly processed directly against the order_item entity. Any other fields, including crucial ones like fulfilled_quantity, were incorrectly routed under a different internal representation (item.item). Since the internal OrderLineItem entity does not directly possess columns named fulfilled_quantity or similar join-entity specific fields, the metadata validation would fail, leading to the query error.

Reproducing the Issue

A typical scenario demonstrating this issue would involve a call to the ESHOPMAN service like this:

const _ = await service.listOrders({
  items: { fulfilled_quantity: 0 },
})

This query, intended to find orders with items that have a fulfilled quantity of zero, would unfortunately throw the aforementioned error.

The ESHOPMAN Solution: A More Robust Admin API

The good news for the ESHOPMAN community is that a dedicated fix has been developed to address this limitation. The solution ensures that the full set of fields available on the order_item join entity—including fulfilled_quantity, shipped_quantity, delivered_quantity, and all other relevant quantity and price fields—are correctly routed and validated when used in filtering operations via the Admin API.

This enhancement brings consistency to ESHOPMAN's API, allowing developers and merchants to leverage the full power of detailed order item filtering. It means that complex queries, essential for inventory management, fulfillment tracking, and advanced reporting within your HubSpot-integrated storefront, will now execute as expected.

Impact and Best Practices for ESHOPMAN Users

This fix significantly improves the flexibility and precision of order management within ESHOPMAN. For developers building custom integrations or extending ESHOPMAN's capabilities, it means more reliable and granular control over order data. For merchants, it translates to better insights and operational efficiency, especially when managing fulfillment workflows directly from your HubSpot environment.

We encourage all ESHOPMAN users to stay updated with the latest platform releases to benefit from such enhancements. This commitment to refining the Admin API ensures that ESHOPMAN remains a leading headless commerce solution, tightly integrated with HubSpot for seamless storefront management and unparalleled data access.

By resolving issues like this, ESHOPMAN continues to empower businesses with the tools needed for advanced, data-driven commerce operations.