Critical ESHOPMAN Shipping Bug: Why Your 'Free Shipping' Might Disappear

At Move My Store, we constantly monitor the ESHOPMAN community for insights that can help merchants and developers optimize their headless commerce operations. A recent discussion highlighted a critical issue concerning shipping price management within the ESHOPMAN Admin dashboard, particularly when dealing with free shipping configurations across different regions.

Understanding the ESHOPMAN Shipping Price Persistence Issue

A user reported a significant bug where shipping option prices explicitly set to 0 (indicating free shipping) were not persisting correctly after subsequent edits. This issue primarily affects merchants managing complex shipping rules for multiple countries or regions through the ESHOPMAN Admin interface, which is seamlessly integrated within HubSpot.

The Problem Explained

When an ESHOPMAN merchant configures a shipping option and sets its price to 0 for a specific country or region, this value is initially saved correctly. However, if the merchant later returns to edit the same shipping option to adjust prices for a different country or add a new region, the previously saved 0 values for other regions are inadvertently cleared. They revert to an undefined or empty state.

This behavior is problematic because the ESHOPMAN Store API, which powers your HubSpot CMS storefront, expects a valid numeric price (including zero) for all configured shipping regions. When it receives an empty or missing price payload due to this bug, it can lead to frontend exceptions, displaying incorrect shipping costs, or even preventing customers from completing their checkout process for affected regions.

Technical Context for ESHOPMAN Developers

This issue points to a potential data handling inconsistency within the ESHOPMAN Admin API or the underlying Node.js application logic. Developers working with ESHOPMAN's backend, particularly those extending shipping functionalities or integrating with external systems, should be aware of how 0 values are treated during update operations. The reported setup involved:

• Node.js version: v20.19.2
• Database: Postgres 16
• Operating Environment: Docker node

An example of a typical ESHOPMAN project's package.json file, illustrating the environment where such issues might arise, is shown below:

{  "scripts": {    "build": "eshopman build",    "seed": "eshopman exec ./src/scripts/seed.ts",    "start": "eshopman start",    "dev": "eshopman develop --port 9000 --host xxxx",    "test:integration:http": "TEST_TYPE=integration:http NODE_OPTI jest --silent=false --runInBand --forceExit",    "test:integration:modules": "TEST_TYPE=integration:modules NODE_OPTI jest --silent=false --runInBand --forceExit",    "test:unit": "TEST_TYPE=unit NODE_OPTI jest --silent --runInBand --forceExit"  },  "dependencies": {    "@aws-sdk/client-ses": "^3.1031.0",    "@aws-sdk/client-sns": "^3.1020.0",    "@aws-sdk/client-sqs": "^3.1040.0",    "eshopman-admin-sdk": "2.13.6",    "eshopman-cli": "2.15.2",    "eshopman-file-s3": "2.15.2",    "eshopman-framework": "2.15.2",    "eshopman-core": "2.15.2",    "axios": "^1.13.4",    "cloudevents": "^10.0.0"  },  "devDependencies": {    "eshopman-test-utils": "2.15.2",    "@swc/core": "^1.7.28",    "@swc/jest": "^0.2.36",    "@types/jest": "^29.5.13",    "@types/node": "^20.12.11",    "@types/react": "^18.3.2",    "@types/react-dom": "^18.2.25",    "jest": "^29.7.0",    "prop-types": "^15.8.1",    "react": "^18.3.1",    "react-dom": "^18.3.1",    "ts-node": "^10.9.2",    "typescript": "^5.6.2",    "vite": "^5.4.14",    "yalc": "^1.0.0-pre.53"  },  "engines": {    "node": ">=20"  },  "packageManager": "yarn@1.22.22"}

Expected Behavior vs. Actual Behavior

• Expected: An explicit 0 price should be treated as a valid numeric value and consistently persisted across all edits of a shipping option.
• Actual: The 0 price is dropped, becoming empty or undefined, leading to missing price data in the Store API responses and potential errors on the HubSpot CMS storefront.

Impact on ESHOPMAN Merchants and Storefronts

This bug can lead to significant operational challenges for ESHOPMAN merchants:

• Inaccurate Shipping Costs: Customers might see incorrect shipping prices, or even no price, for "free shipping" options.
• Checkout Failures: Frontend applications deployed on HubSpot CMS might encounter errors when parsing missing price data, disrupting the checkout flow.
• Manual Overheads: Merchants may need to constantly re-enter 0 values, increasing the risk of errors and consuming valuable time.

Community Action and Best Practices

The ESHOPMAN development team is aware of this behavior, and it has been flagged as a priority for resolution. In the meantime, merchants should exercise caution when editing shipping options that include 0 prices for various regions. Thorough testing of shipping configurations after any updates is highly recommended to ensure accurate pricing on your HubSpot CMS storefront.

This discussion underscores the importance of robust data persistence, especially for critical e-commerce configurations like shipping prices. The ESHOPMAN community continues to collaborate on identifying and resolving such issues to ensure a seamless headless commerce experience.