Ensuring Stable Minimum Spend Promotions in ESHOPMAN: A Workflow Deep Dive

Understanding ESHOPMAN Promotion Challenges: Minimum Spend Rules

As an ESHOPMAN merchant or developer, you rely on robust promotion capabilities to incentivize purchases and manage your storefront effectively within HubSpot. A recent community discussion has highlighted a critical behavior concerning minimum spend promotions that utilize item_total or total rules. This insight explains the issue, its impact, and provides a crucial workaround to ensure your promotions function as expected on your ESHOPMAN-powered HubSpot CMS storefront.

The Silent Disappearing Act: What's Happening?

Imagine setting up an ESHOPMAN promotion, say "SPEND20," offering a 10% discount on items with a minimum item_total of €20. When a customer adds items totaling exactly €20 to their cart and applies the promotion via the ESHOPMAN Store API, it works perfectly at first. The cart's item_total drops to €18, reflecting the discount.

However, the problem arises with the next cart update – for instance, when the customer enters their email or selects a shipping method. During this update, the promotion is silently removed from the cart. Why? Because ESHOPMAN's internal workflow for re-evaluating promotions, updateCartPromotionsWorkflow, checks the promotion rules against the cart's already discounted totals. With the item_total now at €18, the "SPEND20" promotion fails its own minimum requirement (€20), leading to its removal.

This issue specifically affects rules based on item_total and total because these values reflect post-discount amounts. In contrast, rules based on item_subtotal remain unaffected as this value represents the pre-discount total. This distinction is particularly important for stores with tax-inclusive pricing, common in regions like the EU, where merchants typically want minimums to align with the customer-visible, tax-included prices.

Expected Behavior vs. Actual Experience

The expectation is straightforward: once a promotion is validly applied to a cart, its validity should not depend on whether its own discount has already been applied. A cart meeting the initial minimum spend should retain the promotion across subsequent updates, ensuring a consistent customer experience.

Currently, the actual behavior leads to a frustrating user journey where a discount appears, only to vanish silently when the customer proceeds to checkout, creating confusion and potential abandonment.

The ESHOPMAN Workflow Context

The core of this behavior lies within the ESHOPMAN Node.js backend's promotion evaluation logic. The updateCartPromotionsWorkflow fetches cart details, including original_item_total and original_total (the values before any discounts), but these original values are not consistently used when the promotion rules are re-evaluated. Instead, the workflow defaults to using the cart's current, post-discounted totals for the rule context.

Actionable Workaround for ESHOPMAN Developers

Fortunately, ESHOPMAN provides a powerful mechanism – workflow hooks – that allows developers to intervene and correct this behavior. By utilizing the setPromotionContext hook within the updateCartPromotionsWorkflow, you can override the context used for rule evaluation, ensuring promotions are judged against the cart's original, pre-discounted totals.

Here's how you can implement this workaround in your ESHOPMAN Node.js application:

import { updateCartPromotionsWorkflow } from "@eshopman/core-flows"
import { StepResponse } from "@eshopman/framework/workflows-sdk"

updateCartPromotionsWorkflow.hooks.setPromotionContext(({ cart }) => {
  return new StepResponse({ item_total: cart.original_item_total })
})

This code snippet ensures that when promotions are re-evaluated, the item_total used for rule checking is the original_item_total of the cart, effectively preventing the promotion from removing itself. This approach can be extended to total as well if needed.

Conclusion

Understanding and addressing this promotion evaluation nuance is key to delivering a seamless and reliable e-commerce experience on your ESHOPMAN storefront. Implementing this workaround will help maintain the integrity of your minimum spend promotions, ensuring customer trust and satisfaction. Stay tuned to ESHOPMAN community updates for official resolutions and best practices as the platform evolves.