ESHOPMAN Promotion Insight: Mastering "Buy X Get Y" Discounts for Accurate Headless Commerce Pricing

At Move My Store, we believe in empowering ESHOPMAN users with transparent insights into the platform's capabilities and ongoing enhancements. This community insight sheds light on a crucial aspect of promotion management within ESHOPMAN's headless commerce framework, particularly concerning "Buy X Get Y" discounts for storefronts deployed via HubSpot CMS.

Understanding "Buy X Get Y" Discount Accuracy in ESHOPMAN

Accurate promotional pricing is fundamental for any e-commerce operation. A recent discussion within the ESHOPMAN community highlighted an important nuance in how "Buy X Get Y" promotions were being applied, specifically when eligible items had varying quantities and unit prices. This scenario could lead to an unintended outcome where a more expensive item was discounted instead of a cheaper one, impacting profit margins and customer satisfaction.

The Core Issue: Unit Price vs. Line Subtotal Sorting

The challenge arose in ESHOPMAN's promotion engine, which is a core component of its Node.js/TypeScript backend, accessible via the Admin API. When applying a "buy 3, get 1 free" promotion, the system was designed to identify eligible items and then select the target for the discount. However, the logic responsible for ranking eligible lines, intended to prioritize the cheapest item for the discount, was mistakenly sorting by the line subtotal (total price of all units in that line item) rather than the unit price (price per single item).

Consider this scenario:

• Your ESHOPMAN cart contains one unit of Item A priced at $379 (line subtotal: $379).
• It also contains three units of Item B, each priced at $199 (line subtotal: $597).

Under a "buy 3, get 1 free" promotion, the expectation is that the three units of Item B and one unit of Item A would form the 'buy' side, and one unit of Item B (the cheaper item) would be discounted. This would result in a $199 adjustment on the Item B line.

However, due to the sorting logic prioritizing line subtotal, the Item B line (totaling $597) was ranked higher than the Item A line (totaling $379). This led to all three units of Item B being reserved for the 'buy' side, making the single Item A unit the target for the discount. Consequently, the system applied a $379 adjustment on the Item A line, discounting the more expensive item.

Technical Details and Resolution Path

This behavior was traced to a specific comparator within ESHOPMAN's core promotion module logic. The fix identified involves a straightforward adjustment: instead of directly comparing line subtotals, the system needs to calculate the unit price (subtotal ÷ quantity) for each line item before performing the comparison. This ensures that the true cheapest item is correctly identified as the discount target.

For ESHOPMAN developers and those managing their HubSpot-powered storefronts, understanding the underlying dependencies is key. The issue was observed with specific ESHOPMAN core versions:

"@eshopman/eshopman": "2.21.2",
"@eshopman/framework": "2.21.2"

The ESHOPMAN team has acknowledged this as a critical bug and is actively working on integrating the necessary fix. While an automated fix attempt did not complete, the issue has been escalated to the core development team, ensuring a maintainer will implement a robust solution. This ongoing commitment to refining core platform logic is vital for the stability and accuracy of ESHOPMAN's headless commerce capabilities.

Impact and Best Practices for ESHOPMAN Users

For merchants utilizing ESHOPMAN to manage their products and promotions within HubSpot, this insight underscores the importance of thoroughly testing promotional campaigns, especially those involving "Buy X Get Y" structures with varied product quantities. Developers building custom integrations or extending ESHOPMAN's functionality via its Admin API should be aware of how discount allocation is handled and stay updated on platform releases that address such core logic improvements.

Move My Store encourages all ESHOPMAN users to keep their platform versions updated to benefit from these crucial enhancements, ensuring your HubSpot CMS storefronts operate with maximum accuracy and efficiency.