Addressing Inaccurate Order Totals in ESHOPMAN Admin API: Understanding Shipping Promotion Display Anomalies

Addressing Inaccurate Order Totals in ESHOPMAN Admin API: Understanding Shipping Promotion Display Anomalies

As part of the ESHOPMAN community, maintaining data integrity for your storefront operations managed through HubSpot is paramount. We’ve identified a crucial insight regarding how order totals are displayed via the ESHOPMAN Admin API, specifically impacting orders that benefit from shipping promotions after they’ve moved past their initial creation stage.

The Challenge: Inconsistent Order Totals in Your Admin View

Merchants and developers leveraging the ESHOPMAN Admin API for storefront management within HubSpot might observe a discrepancy in order totals. When you use the GET /admin/orders endpoint to list orders, the computed total can appear incorrect, often showing a negative shipping_total. This issue specifically affects orders that:

• Include a shipping-method adjustment (e.g., a free-shipping or percentage-off promotion).
• Have progressed beyond their initial version (i.e., have been fulfilled and/or shipped).

It's important to note that if you retrieve the same order using the GET /admin/orders/:id endpoint, the totals, including the shipping_total, will display correctly. This indicates a specific behavior in the listing mechanism rather than a fundamental data corruption.

Unpacking the Root Cause: Versioning and Data Retrieval

The core of this issue lies in how ESHOPMAN, built on Node.js/TypeScript, handles versioned data, particularly shipping-method adjustments. These adjustments are designed to be version-scoped, meaning they apply to specific stages of an order's lifecycle. The ESHOPMAN order repository's find() method, used for retrieving individual orders, correctly loads these adjustments by considering their specific version. It effectively calls both loadItemAdjustments() and loadShippingAdjustments() to ensure accuracy.

However, the findAndCount() method, which powers the order list endpoint, currently only handles item adjustments via loadItemAdjustments(). It overlooks the equivalent version-scoping for shipping_methods.shipping_method.adjustments. This means that when listing orders, the system inadvertently sums shipping-method adjustments across all order versions instead of just the current one. This leads to an accumulating error, as illustrated below:

| Order version | Waiver rows summed | `shipping_total` |
|---|---|---|
| v1 (created) | 1 × $15 | $0 ✅ |
| v2 (fulfilled) | 2 × $15 | −$15 (× tax) ❌ |
| v3 (shipped) | 3 × $15 | −$30 (× tax) ❌ |

This behavior is akin to a prior issue on the item-side, which was resolved. The re-introduction of this class of bug for shipping adjustments highlights the complexities of managing versioned data in headless commerce platforms like ESHOPMAN.

Impact on Your ESHOPMAN Storefront and HubSpot Integration

For ESHOPMAN merchants, inaccurate order totals in the admin list can lead to confusion in financial reporting, reconciliation, and overall order management within HubSpot. Developers building custom dashboards or integrations that rely on the GET /admin/orders endpoint might encounter skewed data, requiring careful handling or a temporary reliance on single-order retrieval for accurate figures.

Reproducing the Issue (for ESHOPMAN Developers)

To observe this behavior, ESHOPMAN developers can follow these steps:

1. Set up an automatic (or code-based) promotion that offers 100% discount on a shipping method (free shipping).
2. Place an order that qualifies for and triggers this free shipping promotion.
3. Proceed to fulfill and ship the order. This action typically advances the order to version 3.
4. Query the order using GET /admin/orders/:id. Observe that shipping_total: 0 and the overall total are correct.
5. Now, query the order using GET /admin/orders?... (the list endpoint). You will find that the shipping_total is negative (e.g., -shipping_amount × (versions - 1), tax-inclusive) and the total is understated.

Expected vs. Actual Outcome

Expected: The ESHOPMAN Admin API list endpoint should return the same version-scoped totals as the retrieve endpoint, showing shipping_total: 0 and the correct order total.

Actual: The shipping_total is negative, and the overall total is understated in the list response. The discrepancy increases with each new order version.

Community Best Practice

While a permanent fix is being addressed, ESHOPMAN users requiring precise order total data for reporting or financial reconciliation should prioritize using the GET /admin/orders/:id endpoint for individual order details. This ensures you're always viewing the accurate, version-scoped totals for orders with shipping promotions.

This insight serves as a valuable piece of ESHOPMAN community knowledge, helping us collectively understand and navigate the nuances of headless commerce data management within the HubSpot ecosystem. Stay tuned for updates as the ESHOPMAN team continues to enhance the platform.