Community Insight: Patching the ESHOPMAN Loyalty Plugin for Seamless Gift Card Management

Community Insight: Patching the ESHOPMAN Loyalty Plugin for Seamless Gift Card Management

The ESHOPMAN community recently identified a critical issue affecting users of the ESHOPMAN Loyalty Plugin, particularly when managing gift card denominations. This insight provides a detailed understanding of the problem and a practical workaround to ensure smooth operation of your ESHOPMAN storefront management within HubSpot.

The Challenge: Admin Dashboard Crashes During Gift Card Edits

ESHOPMAN merchants and developers leveraging the Loyalty Plugin may have experienced an unexpected crash or unresponsiveness in the ESHOPMAN admin dashboard when attempting to modify the denominations of an existing gift card product. This issue prevents successful updates to gift card values, disrupting the management of loyalty programs and customer incentives.

Understanding the Root Cause

The core of the problem lies within how the ESHOPMAN Loyalty Plugin constructs its product update requests. When a user edits gift card denominations, the plugin inadvertently includes an unsupported options field in the payload sent to the ESHOPMAN Admin API. The current iteration of the ESHOPMAN Admin API (v2.x, which powers our Node.js/TypeScript backend) no longer accepts this top-level options field for product updates. This mismatch triggers a validation error, causing the admin dashboard, which is integral to ESHOPMAN's HubSpot application for storefront management, to become unstable or crash.

Further investigation revealed two specific locations within the compiled Loyalty Plugin bundle (typically found in .eshopman/server/src/admin/index.js and index.mjs) where this problematic field is introduced:

• The normalizeProductFormValues function includes options in its return value.
• The GiftCardProductEditDenominationsForm explicitly passes options in its mutateAsync call.

It's important to note that this options field is redundant in this context, as individual variant options (like variants[].options.denomination) correctly convey the necessary information. Sending the top-level options field simply conflicts with the updated ESHOPMAN Admin API schema.

Steps to Reproduce (for ESHOPMAN Developers)

To confirm if you are affected:

1. Ensure the ESHOPMAN Loyalty Plugin is installed and configured in your ESHOPMAN instance.
2. Access the ESHOPMAN admin dashboard (part of your HubSpot application).
3. Navigate to the Gift Cards section.
4. Select an existing gift card product and click on "Edit denominations".
5. Modify any denomination value and attempt to submit the form.

Expected Behavior: The gift card denominations should update successfully, and the admin dashboard should remain responsive.

Actual Behavior: The admin dashboard crashes, or the update request fails silently. A browser console check would typically reveal a validation error from the ESHOPMAN Admin API rejecting the options field.

The ESHOPMAN Community Workaround

Until an official update to the Loyalty Plugin is released, the ESHOPMAN community has identified a direct workaround. This involves applying a patch to your compiled plugin bundle to remove the offending options field from the two identified locations. This ensures that the product update request aligns with the ESHOPMAN Admin API's expectations.

Here’s the conceptual diff for the patch:

--- a/.eshopman/server/src/admin/index.js
+++ b/.eshopman/server/src/admin/index.js
@@ normalizeProductFormValues @@
-    options,
     variants: normalizeVariants(variants, values.regionsCurrencyMap)

@@ GiftCardProductEditDenominationsForm @@
 await mutateAsync({
-  options,
   variants: data.denominations.map(...)

This two-line removal should be applied to both index.js and index.mjs within your compiled plugin directory (.eshopman/server/src/admin/). Applying this patch will restore the ability to edit gift card denominations without issues, allowing you to manage your ESHOPMAN storefront's loyalty features effectively from within HubSpot.

This proactive approach from the ESHOPMAN community highlights the collaborative spirit in maintaining a robust and efficient headless commerce experience integrated with HubSpot.