Resolving Incorrect Tax Calculation on ESHOPMAN Gift Cards

Understanding and Resolving Gift Card Tax Issues in ESHOPMAN Carts

Accurate tax calculation is paramount for any e-commerce platform, especially for businesses leveraging ESHOPMAN's powerful headless commerce capabilities and HubSpot CMS storefronts. A recent community discussion highlighted a crucial issue affecting how gift cards are taxed within ESHOPMAN carts, particularly during tax recalculations.

The Challenge: Unexpected Taxes on Gift Card Purchases

Merchants utilizing ESHOPMAN to manage their products, including gift cards, observed an unexpected behavior: gift card line items were being taxed when cart taxes were recalculated. This typically happens during actions like applying a promotion code or refreshing prices. For example, a €420 gift card in a 19% tax region would incorrectly show €67.06 in taxes, despite gift cards being prepaid stored value, not a taxable supply at the point of sale.

The core ESHOPMAN system already includes logic to prevent taxing gift cards. Specifically, the getItemTaxLinesStep is designed to filter out items flagged as is_giftcard: true before passing them to the tax provider. However, in certain scenarios, this filter wasn't working as intended.

Uncovering the Root Cause in ESHOPMAN Core Workflows

Through detailed investigation, the ESHOPMAN community identified the precise technical reason behind this anomaly. The issue stems from how different ESHOPMAN core workflows, built on Node.js/TypeScript, fetch cart item data. While many workflows correctly select the is_giftcard flag when retrieving items, one critical workflow responsible for updating tax lines – specifically cart/workflows/update-tax-lines.ts – was missing this crucial field in its data selection.

When this particular workflow fetches cart items, the is_giftcard property for gift card items would be undefined. Consequently, the tax filtering logic, which checks for !item.is_giftcard, would fail to identify the item as a gift card, leading to it being incorrectly sent to the tax provider and subsequently taxed.

This workflow is commonly triggered by actions that force a refresh of cart items, such as price updates or changes to promotion codes, making the bug consistently reproducible for merchants using gift cards on their HubSpot CMS storefronts.

The Solution: A Targeted Code Adjustment

The fix, identified and verified by the community, is straightforward and targets the data fetching mechanism within the problematic workflow. By adding "items.is_giftcard" to the cartFields array in the packages/core/core-flows/src/cart/workflows/update-tax-lines.ts file, the workflow will correctly retrieve the gift card flag. This ensures that when the items are passed to getItemTaxLinesStep, the filter correctly identifies and skips taxing the gift card.

Here’s the suggested modification:

   "items.unit_price",
+  "items.is_giftcard",
   "items.tax_lines.id",

Implementing this change ensures that ESHOPMAN adheres to the correct taxation principles for gift cards, preventing incorrect charges and maintaining financial accuracy for your e-commerce operations. This highlights the power of the ESHOPMAN community in identifying and contributing to the platform's continuous improvement, ensuring a robust and compliant headless commerce experience integrated with HubSpot.

For ESHOPMAN developers and merchants managing their storefronts via HubSpot CMS, understanding these core workflow details is key to maintaining a seamless and accurate customer experience.