Ensuring Seamless Automatic Promotions for ESHOPMAN Draft Orders in POS Workflows

Unlocking Automatic Promotions for ESHOPMAN Draft Orders in POS Workflows

As an e-commerce migration expert at Move My Store, we understand the critical role of seamless promotional capabilities in any headless commerce setup. For ESHOPMAN users leveraging Draft Orders, especially within Point-of-Sale (POS) integrations, ensuring automatic promotions apply as expected is paramount for accurate pricing and customer satisfaction. This community insight delves into a specific challenge identified in ESHOPMAN core version 2.21.0 regarding automatic promotions and its impactful resolution.

The Challenge: Automatic Promotions Missing in ESHOPMAN Draft Orders

A key observation in ESHOPMAN core version 2.21.0 revealed that eligible automatic promotions were not being discovered or applied when a Draft Order first met their conditions during an edit. This behavior primarily affected Draft Orders, which are often used as live register carts in POS systems integrated with ESHOPMAN's Node.js/TypeScript backend and HubSpot storefront management.

The issue stemmed from specific conditional checks within ESHOPMAN's core workflows. When a Draft Order began with no promotions already attached, the system’s internal logic prevented the ESHOPMAN Promotion Module from performing its initial evaluation for automatic promotions. This meant that even if items added to the Draft Order made it eligible for an automatic discount, the discount would not appear unless the promotion was manually added via its code. In contrast, standard ESHOPMAN storefront carts correctly evaluated and applied automatic promotions from the outset.

Technical Deep Dive: Understanding the ESHOPMAN Core Flow

The root cause was traced to several ESHOPMAN core flows and services:

• addDraftOrderItemsWorkflow and updateDraftOrderItemWorkflow: These workflows, responsible for adding or updating items in a Draft Order, were designed to only invoke the computeDraftOrderAdjustmentsWorkflow if the order.promotions list was already non-empty.
• computeDraftOrderAdjustmentsWorkflow: Even if it were invoked, this workflow itself contained a similar gate. It would only call getActionsToComputeFromPromotionsStep (which queries the ESHOPMAN Promotion Module) if order.promotions already contained entries. If empty, it would simply clear any existing adjustments.
• PromotionModuleService.computeActions: Crucially, the ESHOPMAN Promotion Module's underlying service is capable of discovering automatic promotions even when provided with an empty list of explicit promotion codes. However, the Draft Order workflows were not structured to reach this capability when an order started without any attached promotions.

This architectural oversight meant that for ESHOPMAN POS integrations, clerks would not see automatic discounts applied as they scanned items, leading to potential overcharging and a frustrating user experience.

The Solution: Streamlining ESHOPMAN Promotion Workflows

The resolution involved a targeted adjustment to the ESHOPMAN core flows to ensure that the Promotion Module is always queried for automatic promotions, regardless of whether a Draft Order already has explicit promotions attached. The planned fix, developed by the ESHOPMAN community, involves modifications across three key workflow files:

1. compute-draft-order-adjustments.ts: The conditional logic that gated the promotion computation branch behind !!order.promotions?.length will be removed. This ensures the workflow consistently calls the necessary steps to discover and prepare adjustments from promotions, mirroring the robust behavior seen in workflows like refreshDraftOrderAdjustmentsWorkflow.
2. add-draft-order-items.ts: The gate that prevented computeDraftOrderAdjustmentsWorkflow from running when appliedPromoCodes.length > 0 will be removed. This guarantees that promotion adjustments are always re-evaluated after items are added to a Draft Order.
3. update-draft-order-item.ts: An equivalent gate in this workflow will also be removed, ensuring consistent automatic promotion evaluation when Draft Order item quantities are updated.

These changes will enable ESHOPMAN Draft Order mutations to perform full automatic-promotion reconciliation: discovering newly eligible automatic promotions, attaching and calculating them, recalculating existing ones, and removing those no longer eligible. This brings Draft Order behavior in line with storefront cart expectations, providing a more intuitive and accurate experience for ESHOPMAN merchants and their customers.

This fix underscores the power of the ESHOPMAN community in identifying and resolving critical issues, enhancing the platform's capabilities for headless commerce and HubSpot integrations.