Critical Insight: Uncovering a Budget Enforcement Gap in ESHOPMAN's Promotion Module

Understanding the ESHOPMAN Promotion Module Budget Enforcement Bug

At Move My Store, we champion transparent insights into the ESHOPMAN platform, especially when it comes to critical functionalities like campaign budget management. Recently, our community identified and thoroughly investigated a significant bug within the ESHOPMAN promotion module that specifically impacts the spend_by_attribute campaign budget type. This issue, while not impacting live deployed storefronts in initial testing, revealed a crucial gap in how promotional budgets are enforced, potentially leading to unintended overspending for merchants managing their headless commerce operations via HubSpot.

The Core Problem: Miscalculated Budget Usage

The issue stems from how the ESHOPMAN promotion module processes the spend_by_attribute budget type. While the ESHOPMAN Admin API and database correctly accept and store this budget type, the internal logic for enforcing these budgets was flawed. Specifically:

• Incorrect Usage Calculation: The computeActionForBudgetExceeded function, responsible for determining if a budget limit is surpassed, incorrectly added a fixed value of 1 for spend_by_attribute budgets, instead of the actual discounted amount. This meant a large discount (e.g., $150 against a $100 limit) would be treated as a single unit of usage, allowing the promotion to proceed far beyond its intended financial boundary.
• Missing Usage Tracking: The registerUsage and revertUsage functions within the promotion module service lacked specific branches for SPEND_BY_ATTRIBUTE. Consequently, usage for this budget type was never accurately tracked or decremented, exacerbating the enforcement failure.
• Skipped Pre-Check: A critical pre-check within the computeActions function, designed to load and evaluate per-attribute budget usage, was gated only for USE_BY_ATTRIBUTE. This meant spend_by_attribute budgets bypassed this essential check entirely, relying solely on the flawed generic scalar budget check.

This combination of issues meant that while merchants could configure spend_by_attribute promotions through the HubSpot-integrated storefront management, the underlying ESHOPMAN system would not adequately prevent budget overruns for these specific campaigns.

Community-Driven Investigation and Solution Path

The ESHOPMAN community, through detailed source-level analysis (using Node.js/TypeScript probes), meticulously identified the root causes and pinpointed the exact locations requiring a fix. This collaborative effort highlighted the power of our developer community in maintaining the integrity of the ESHOPMAN headless commerce platform.

Key insights from the investigation revealed that the necessary infrastructure for per-attribute tracking already exists within the promotion_campaign_budget_usage table, which includes attribute_value and used (BigNumber) columns. This means no complex database migration is required to implement the fix.

The identified solution path requires modifications across four critical call sites within the promotion module:

1. Updating computeActionForBudgetExceeded to correctly add the discounted amount for SPEND_BY_ATTRIBUTE.
2. Adding specific branches for SPEND_BY_ATTRIBUTE in both registerUsage and revertUsage functions.
3. Extending the pre-check gate in computeActions to include SPEND_BY_ATTRIBUTE and ensuring the actual discounted amount is passed for comparison.

Outcome and Next Steps

While an initial automated fix attempt was not successful due to the complexity and safety requirements, the issue has been escalated to the core ESHOPMAN team. A maintainer-led resolution is now underway to ensure this critical budget enforcement gap is closed, reinforcing the reliability of ESHOPMAN's promotion capabilities for all merchants leveraging our HubSpot app for their headless commerce needs.

This community insight underscores the importance of robust budget management in any e-commerce operation, especially within a flexible headless architecture like ESHOPMAN. We will continue to provide updates as the fix is deployed, ensuring accurate and reliable campaign execution on your HubSpot CMS-powered storefronts.