Troubleshooting ESHOPMAN Store Credit Workflows: When 'Zero' Means 'Full Balance'

As e-commerce experts at Move My Store, we frequently delve into the intricacies of platforms like ESHOPMAN to ensure seamless operations for merchants. ESHOPMAN, with its powerful headless commerce capabilities and deep integration with HubSpot for storefront management and deployment via HubSpot CMS, provides a robust foundation for online businesses. However, like any sophisticated system, understanding its nuances is key to leveraging its full potential.

Recently, our community identified an important behavior within ESHOPMAN's loyalty features, specifically concerning the addStoreCreditsToCartWorkflow. This workflow is crucial for managing how store credits are applied or removed from a customer's cart, directly impacting the checkout experience on your HubSpot-deployed storefront.

The Unexpected Behavior: Zero Amount Applying Full Balance

A common scenario for developers is to programmatically adjust store credits. For instance, you might want to remove an existing store credit line from a cart. The intuitive approach would be to call the addStoreCreditsToCartWorkflow with an amount of 0, expecting it to clear any existing store credit lines without adding a new one. However, an unexpected behavior was observed:

• When a cart already contained a store credit line.
• And the customer had a positive store credit account balance (e.g., $16.5).
• Executing the workflow with amount: 0 resulted in the existing credit line being deleted, but a new credit line was created for the customer's full store credit account balance (e.g., $16.5).

This contradicts the workflow's intended behavior, which is to remove existing store credit lines and create a new one only for the specified amount. When 0 is specified, no new line should be created.

Reproducing the Scenario

Developers can reproduce this behavior using the ESHOPMAN Admin API or directly within Node.js/TypeScript services that interact with the platform's workflows:

await addStoreCreditsToCartWorkflow(container).run({
  input: {
    cart_id,
    amount: 0,
  },
})

Uncovering the Cause: A Truthiness Check Anomaly

Upon investigation, the root cause was traced to how the workflow internally determines the amount to apply. Within the computeCreditLineActionsStep, a truthiness check was being used:

let amount = input.amount
  ? MathBN.convert(input.amount)
  : MathBN.convert(storeCreditAccount.balance)

In JavaScript and TypeScript, the number 0 is considered a "falsy" value. Because of this, when input.amount was 0, the condition input.amount ? ... evaluated to false. Consequently, the workflow fell back to the alternative expression, which retrieves and applies the customer's full storeCreditAccount.balance instead of respecting the specified 0 amount.

The ESHOPMAN Community Solution: An Explicit Defined Check

The ESHOPMAN community quickly identified a precise and effective solution. By replacing the truthiness check with an explicit check for whether input.amount is defined (i.e., not null or undefined), the workflow can correctly interpret 0 as a valid, specified amount. This ensures that when 0 is passed, no new store credit line is created, effectively removing existing credits without replacement.

let amount = isDefined(input.amount)
  ? MathBN.convert(input.amount)
  : MathBN.convert(storeCreditAccount.balance)

This small but significant change ensures that ESHOPMAN developers have precise control over store credit application, aligning the workflow's behavior with expectations for managing loyalty programs within their HubSpot-integrated headless commerce setup.

Best Practices for ESHOPMAN Developers

This insight highlights the importance of understanding the underlying logic of ESHOPMAN's Node.js/TypeScript workflows when performing custom development or integrating with the Admin API. Always validate input handling, especially with numerical values that can be 0, to prevent unintended side effects on your ESHOPMAN storefronts managed through HubSpot CMS.

By staying informed and leveraging community knowledge, ESHOPMAN users can continue to build powerful and reliable e-commerce experiences.