Deep Dive: Ensuring Reliable Order Confirmations in ESHOPMAN's Headless Commerce

As an e-commerce migration expert at Move My Store, we often delve into the intricacies of headless commerce platforms like ESHOPMAN to ensure our clients build robust and reliable storefronts. A critical component of any online store is the order confirmation notification. It's the first touchpoint after a customer makes a purchase, providing reassurance and essential details.

Recently, our ESHOPMAN community identified a significant insight regarding the platform's default order confirmation notifications. This discussion sheds light on why the out-of-the-box setup for sending order confirmations might not be functioning as expected, and what developers can do to address it.

The Challenge: Missing Order Confirmation Events

The core of the issue lies in how ESHOPMAN's event system interacts with its default notification subscriber. ESHOPMAN, built on Node.js/TypeScript, includes a configurable notification system designed to handle various events. Specifically, the default order confirmation is wired declaratively in the system's core, listening for an event named order.created.

const handlerC
  {
    event: "order.created",
    template: "order-created-template",
    channel: "email",
    to: "order.email",
    // ... other configurations
  },
]

However, through detailed investigation, it was discovered that the order.created event is never actually emitted by ESHOPMAN's order module. This means the subscriber designed to send order confirmations never triggers, leading to a silent failure: no error logs, no notifications sent, and no indication to the merchant or developer that a crucial part of the customer journey is missing.

Understanding ESHOPMAN's Event Asymmetry

Further analysis revealed an asymmetry in how different entities emit "created" events:

• When a customer is created via the Store API, ESHOPMAN emits both customer.created and customer.customer.created.
• When an order is created (e.g., through the Store API checkout process), only order.order.created is emitted by the underlying ORM. The explicit order.created event, similar to customer.created, is absent from the OrderWorkflowEvents enum.

This distinction is crucial. The notification handler, expecting order.created, simply doesn't receive the event it's configured for.

The Payload Predicament

Even if the order.order.created event (which does fire) were listened to, another challenge arises with the event payload. The probe recorded that the order.order.created event carries only the order's ID:

event=order.order.created data={"id":"order_01M0JBGBCWTDVZNVGQ7H36KBF3"}

The default handler, however, attempts to map the recipient using to: "order.email". With a payload containing only id, attempting to extract order.email would result in an undefined recipient, meaning the notification would still fail to send even if the event listener were corrected.

Suggested Solutions and Best Practices for ESHOPMAN Developers

To ensure reliable order confirmations within your ESHOPMAN headless commerce setup, especially when deploying storefronts via HubSpot CMS, consider the following:

• Listen for order.placed: The most appropriate event for customer-initiated order confirmations is order.placed. This event is emitted specifically when a customer completes their cart workflow, ensuring confirmations are sent only for actual placed orders, not drafts or admin-created orders.
• Load Full Order Data: Since event payloads for orders currently only carry the ID, your notification handler will need to query the ESHOPMAN Admin API or Store API to fetch the complete order details, including the customer's email address and other necessary information for the confirmation template.
• Evaluate Notification Handler Design: This scenario highlights a need for more flexibility in ESHOPMAN's declarative notification configuration. Developers might need to either extend the declarative config with a resolver step to fetch data or convert the notification handler into a more robust, ordinary subscriber that can perform custom data fetching logic.

This insight is vital for ESHOPMAN developers and merchants leveraging its Node.js/TypeScript foundation and HubSpot integration. Understanding these nuances allows for the creation of more resilient and functional headless commerce experiences, ensuring that essential customer communications, like order confirmations, are delivered without fail.