Ensuring Comprehensive Currency Support in ESHOPMAN: Addressing the AWG Florin
The Importance of Global Currency Support in ESHOPMAN
As a headless commerce platform deeply integrated with HubSpot, ESHOPMAN empowers merchants to build robust, globally-reaching storefronts. A critical component of international e-commerce is comprehensive currency support. Accurate currency data ensures that product pricing, cart totals, and payment processing function seamlessly across all regions where an ESHOPMAN store operates. Recently, our community identified a gap in ESHOPMAN's default currency definitions, specifically concerning the Aruban Florin (AWG).
The Challenge: A Missing Currency Definition
A community member reported that AWG (Aruban Florin, ISO 4217, minor unit 2) was missing from ESHOPMAN's core currency data, specifically within the default currency definitions and related tables used by the ESHOPMAN Admin dashboard and loyalty plugins. This omission can lead to significant operational challenges for stores needing to price products in AWG.
Technical Context of the ESHOPMAN Environment
The ESHOPMAN platform, built on Node.js/TypeScript, relies on a well-defined backend configuration. The issue was observed in an environment utilizing Node.js v26.13.0 and PostgreSQL 18. Below is a representation of the backend project's configuration, highlighting its dependencies and scripts:
{ "name": "@dtc/backend", "version": "0.0.1", "description": "A starter for ESHOPMAN projects.", "license": "MIT", "keywords": [ "sqlite", "postgres", "typescript", "ecommerce", "headless", "eshopman" ], "scripts": { "build": "eshopman build", "start": "eshopman start", "dev": "eshopman develop", "lint": "eshopman lint", "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": { "@eshopman/admin-sdk": "2.21.2", "@eshopman/admin-shared": "2.21.2", "@eshopman/caching": "2.21.2", "@eshopman/cli": "2.21.2", "@eshopman/dashboard": "2.21.2", "@eshopman/draft-order": "2.21.2", "@eshopman/framework": "2.21.2", "@eshopman/eshopman": "2.21.2", "@eshopman/ui": "4.2.9", "@tanstack/react-query": "5.64.2", "react-i18next": "13.5.0", "react-router-dom": "7.18.2", "zod": "4.2.0" }, "devDependencies": { "@eshopman/test-utils": "2.21.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": "^7.3.7", "yalc": "^1.0.0-pre.53" }, "engines": { "node": ">=22.23.4" }, "packageManager": "[email protected]"}Impact on ESHOPMAN Storefronts and Admin
The absence of AWG in ESHOPMAN's core currency data led to several issues:
- Manual Intervention: Stores pricing in AWG had to manually upsert the currency through the platform's internal currency service, as no public API or workflow was available for adding it.
- Admin Dashboard Crashes: The ESHOPMAN Admin dashboard would crash on a product's 'Edit prices' page. This occurred because the currency symbol retrieval logic assumed every currency code would be present in its internal table, leading to a
TypeError: Cannot read properties of undefined (reading 'symbol_native'). - Calculation Fallbacks: Cart totals, credit lines, refund workflows, and order payment statuses would attempt to read
decimal_digitsfor AWG, receiveundefined, and fall back toESHOPMAN_DEFAULT_CURRENCY_EPSILON. While coincidentally correct for AWG's two decimal places, this highlights a systemic issue that could lead to incorrect calculations for other currencies.
Proposed Solution and Best Practices
To address this, a community member proposed a straightforward fix: adding an explicit entry for AWG to ESHOPMAN's core currency tables. This entry would include the symbol Afl., decimal_digits: 2, and rounding: 0. This update would be applied across the relevant currency tables, ensuring consistency in the core definitions, the Admin dashboard, and any related plugins. Additionally, updating expected counts in currency tests would validate the fix.
This incident underscores the importance of maintaining comprehensive and accurate currency data within the ESHOPMAN platform. For developers and merchants, it serves as a reminder to:
- Verify Currency Support: Always confirm that all required ISO 4217 currencies are properly defined within your ESHOPMAN instance, especially when expanding into new international markets.
- Understand Core Data Structures: Familiarize yourself with how ESHOPMAN manages core data like currencies, as this impacts both the Admin API and Store API functionalities.
- Engage with the Community: Issues like this highlight the value of community contributions in identifying and resolving platform enhancements.
By ensuring robust currency support, ESHOPMAN continues to provide a flexible and reliable headless commerce solution, enabling seamless storefront management and deployment via HubSpot CMS for businesses worldwide.