Resolving ESHOPMAN Admin API Query Errors for Order Totals After Platform Updates

Troubleshooting ESHOPMAN Order Listing with Totals via Admin API

As an e-commerce expert at Move My Store, we understand the importance of seamless data retrieval for managing your ESHOPMAN storefront. Recently, some ESHOPMAN users and developers have encountered a specific error when attempting to list orders and retrieve their total values using the Admin API's query.graph function. This issue primarily manifests after platform updates, leading to HTTP 500 errors and hindering critical storefront management operations within HubSpot.

The Problem: 'Shipping method version is required' Error

After recent ESHOPMAN platform updates, particularly affecting versions around 2.18.0, any query.graph call designed to list multiple orders and include fields like total will throw an error:

Error: Shipping method version is required to load adjustments
    at node_modules/@medusajs/order/src/utils/base-repository-find.ts:491:13
    at Array.map ()
    at loadShippingAdjustments (node_modules/@medusajs/order/src/utils/base-repository-find.ts:484:34)

This error prevents the successful retrieval of order lists when aggregate totals are requested, impacting features like customer order history, staff order lists, and dashboard statistics routes within your HubSpot-managed storefront. Interestingly, retrieving a single order by ID with totals, or listing orders without requesting totals, continues to function correctly.

Here's an example of a problematic query:

const query = container.resolve(ContainerRegistrationKeys.QUERY)

await query.graph({
  entity: "order",
  fields: ["id", "total"],
  pagination: { skip: 0, take: 3, order: { created_at: "DESC" } },
})
// This query throws the error.

Understanding the Root Cause in ESHOPMAN's Node.js Backend

Investigation into the ESHOPMAN platform's Node.js/TypeScript backend reveals that the issue stems from an internal conditional logic within the order module's data retrieval process. When listing orders and calculating totals, the system requires a version field from the shipping methods to correctly load adjustments. However, this crucial shipping_methods.version field is only appended to the database SELECT statement if the caller's field list explicitly contains an entry like shipping_methods.shipping_method.*. If only total is requested without this specific shipping method detail, the version data is never selected, leading to the runtime error.

The Actionable Workaround for ESHOPMAN Developers

Fortunately, a straightforward workaround exists for developers interacting with the ESHOPMAN Admin API. To resolve the 'Shipping method version is required' error, you must explicitly include any field under shipping_methods.shipping_method. in your query.graph request. This forces the platform's internal logic to select the necessary version data, allowing totals to be calculated successfully.

Here's how to modify your query:

const query = container.resolve(ContainerRegistrationKeys.QUERY)

await query.graph({
  entity: "order",
  fields: ["id", "total", "shipping_methods.shipping_method.id"], // Add this field!
  pagination: { skip: 0, take: 3, order: { created_at: "DESC" } },
})
// This query now returns rows with correct totals.

By adding "shipping_methods.shipping_method.id" (or any other specific field from shipping_methods.shipping_method.), you ensure that the required version information is retrieved, allowing the ESHOPMAN backend to process the order totals without error. Note that using wildcards like "shipping_methods.shipping_method.*" or simply "shipping_methods.shipping_method" might not work as expected and could still lead to errors.

Important Considerations for ESHOPMAN Integrations

• Previous Versions: This issue isn't entirely new; similar 'missing version' problems could occur in earlier ESHOPMAN versions (e.g., 2.17.2) if the skip parameter was omitted from pagination objects when requesting totals. The workaround applies there too.
• Silent Totals Issue: While investigating, some developers observed that requesting items.item.id alongside totals might silently return total: 0 and subtotal: 0 without an error. This is a separate, non-regression issue, but something to be aware of if you're experiencing incorrect totals. Requesting items.* plus items.detail.* typically resolves this.

Implementing this workaround is crucial for maintaining the integrity and functionality of your ESHOPMAN storefront management within HubSpot, ensuring that your Admin API queries for order totals execute reliably.