Clarifying ESHOPMAN Shipping Calculations: Understanding Item Total vs. Subtotal

One of the most common areas of confusion for e-commerce merchants and developers alike revolves around how shipping fees are calculated, especially concerning the inclusion or exclusion of taxes. Within the ESHOPMAN platform, designed as a headless commerce solution integrated with HubSpot, this topic recently sparked a valuable discussion in our community. Understanding ESHOPMAN's core behavior is crucial for accurate storefront management and seamless customer experiences deployed via HubSpot CMS.

A recent query from an ESHOPMAN user highlighted a perceived change in how shipping fees were calculated. The user noted that shipping prices seemed to be based on the item_total, which includes taxes, rather than the item_subtotal, which represents the pre-tax value of items. This observation led to questions about whether this was a recent regression or an intentional design choice, particularly regarding the logic of applying shipping fees to a tax-inclusive total.

The ESHOPMAN Core Behavior Explained

Upon investigation and clarification from the ESHOPMAN core team, it was confirmed that the platform's current behavior is indeed intentional and well-documented. For shipping price rules within ESHOPMAN, the system explicitly uses the item_total attribute. This item_total is defined as the sum of all line-item totals after any applicable discounts have been applied, and crucially, it includes taxes.

This means that when you configure shipping options and their associated price rules through the ESHOPMAN Admin API, any conditions or calculations based on the total value of items in a customer's cart will reference this tax-inclusive item_total. The platform's architecture, built on Node.js/TypeScript, is designed to consistently apply this logic across all storefronts managed via HubSpot.

Why This Matters for Your HubSpot Storefront

For ESHOPMAN merchants and developers managing their e-commerce operations within HubSpot, this understanding is paramount:

• Configuration Accuracy: When setting up shipping rules in your ESHOPMAN instance, be aware that any thresholds or percentage-based calculations for shipping will factor in the total value of items including taxes. This ensures your shipping strategy aligns with the platform's foundational logic.
• Transparency: While the calculation method is internal, understanding it helps in explaining potential discrepancies to customers or in designing clearer checkout experiences on your HubSpot CMS-deployed storefront.
• Development & Integration: Developers working with the ESHOPMAN Admin API to create custom shipping logic or integrate with third-party shipping providers must account for the item_total attribute's definition. Attempting to use a pre-tax item_subtotal attribute for shipping price rules is not currently supported by the core platform.

The user's initial query, though framed as a potential bug, served as an excellent opportunity to clarify this fundamental aspect of ESHOPMAN's commerce engine. The discussion highlighted that the system's design prioritizes a consistent calculation method for shipping, leveraging the final, tax-inclusive item_total.

Considering Alternative Calculation Methods

If your business model or regional tax regulations necessitate calculating shipping fees based on a pre-tax item_subtotal, the appropriate path forward would be to submit a feature request to the ESHOPMAN team. The platform is continuously evolving, and community feedback plays a vital role in shaping future enhancements. Such a feature request would outline the need for a new attribute, like item_subtotal, to be made available for shipping price rules.

In summary, ESHOPMAN's core platform, powering your headless commerce storefronts on HubSpot CMS, intentionally calculates shipping fees using the item_total, which encompasses both product prices and applicable taxes after discounts. This is a documented behavior, and understanding it is key to effectively managing your shipping strategy and developing robust integrations with the ESHOPMAN Admin API.