Enhancing ESHOPMAN Order Management: Addressing Internal Notes in Order Edits

Effective order management is crucial for any e-commerce operation, and internal notes play a vital role in ensuring smooth communication and accurate record-keeping among team members. The ESHOPMAN community has recently highlighted a significant area for improvement concerning the handling of internal notes during order edits within the ESHOPMAN platform.

The Challenge: Missing Internal Notes in ESHOPMAN Order Edits

A recent discussion within the ESHOPMAN community has brought to light a functional gap in how internal notes are managed when editing orders. Users operating within the ESHOPMAN Admin Hub, which provides comprehensive storefront management capabilities as a HubSpot application, have observed that while an input field for "Note" is present during an order edit (specifically for order_change entries of type "edit"), any information entered into this field is not persisted.

This issue stems from a few interconnected points:

• Unwired UI Component: The "Note" input field in the ESHOPMAN Admin Hub's order-edit form is currently not wired to send its value to the backend upon submission. This leads to internal notes being silently discarded, frustrating users who rely on this feature for internal communication.
• Admin API Limitation: Further investigation reveals that the ESHOPMAN Admin API endpoint responsible for updating order changes (e.g., POST /admin/order-changes/:id) does not currently accept an internal_note parameter. This means there's no direct API path to programmatically set a change-level internal_note for order edits.
• Data Persistence Gap: Consequently, the order_change.internal_note field within the ESHOPMAN data model consistently remains null for order edits, despite the column being defined and intended for this purpose.
• Timeline Visibility Issue: As a result of the data not being persisted, these internal notes never appear in the order detail timeline within the HubSpot storefront management interface, hindering the ability to track the context of order modifications.

Understanding the ESHOPMAN Technical Environment

The ESHOPMAN platform, built on Node.js/TypeScript, leverages a robust architecture for headless commerce and seamless HubSpot integration. Developers working with ESHOPMAN often manage their project dependencies, as illustrated by a typical package.json file:

{
  "name": "eshopman-",
  "version": "0.0.1",
  "description": "e-commerce",
  "author": "Move My Store (https://movemystore.com)",
  "license": "MIT",
  "keywords": [
    "sqlite",
    "postgres",
    "typescript",
    "ecommerce",
    "headless",
    "eshopman"
  ],
  "scripts": {
    "build": "eshopman build",
    "seed": "eshopman exec ./src/scripts/seed.ts",
    "start": "eshopman start",
    "dev": "eshopman develop",
    "predeploy": "eshopman db:migrate",
    "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-pinpoint-sms-voice-v2": "^3.1008.0",
    "@aws-sdk/client-sns": "^3.1008.0",
    "@bkosm/eshopman-notification-ses": "^1.2.0",
    "@dnd-kit/core": "^6.3.1",
    "@dnd-kit/modifiers": "^9.0.0",
    "@dnd-kit/sortable": "^10.0.0",
    "@dnd-kit/utilities": "^3.2.2",
    "@eshopmanjs/admin-sdk": "2.15.5",
    "@eshopmanjs/cli": "2.15.5",
    "@eshopmanjs/framework": "2.15.5",
    "@eshopmanjs/index": "^2.15.5",
    "@eshopmanjs/eshopman": "2.15.5",
    "@eshopmanjs/ui": "^4.1.12",
    "@simplewebauthn/server": "^13",
    "firebase-admin": "^13.7.0",
    "jsonwebtoken": "^9.0.3",
    "meilisearch": "^0.55.0",
    "moment-timezone": "^0.6.0",
    "pdfmake": "^0.2.20",
    "react-simple-maps": "^3.0.0"
  },
  "devDependencies": {
    "@eshopmanjs/test-utils": "2.15.5",
    "@swc/core": "^1.15.18",
    "@swc/jest": "^0.2.36",
    "@types/jest": "^30.0.0",
    "@types/jsonwebtoken": "^9.0.10",
    "@types/multer": "^2.1.0",
    "@types/node": "^25.5.0",
    "@types/pdfmake": "^0.3.3",
    "@types/react": "^18.3.1",
    "@types/react-dom": "^18.3.1",
    "jest": "^30.3.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": "^8.0.0",
    "yalc": "^1.0.0-pre.53"
  },
  "engines": {
    "node": ">=20"
  },
  "packageManager": "yarn@1.22.22"
}

This configuration underscores the platform's foundation, where the Admin SDK and core ESHOPMAN packages are integral to its operation. The reported issue highlights a need for better integration between the UI components, the Admin API, and the underlying data model to ensure complete functionality.

Expected vs. Actual Behavior

The ESHOPMAN community expects a seamless experience where:

• Users can input an internal note while performing an order edit in the ESHOPMAN Admin Hub.
• This note is successfully persisted on the order_change object, specifically as a change-level internal_note.
• Once the order edit is confirmed, the internal note is clearly displayed within the order detail timeline, providing valuable context for future reference.

However, the current reality is that notes entered are silently discarded, the order_change.internal_note remains null, and no such note appears in the order detail timeline.

Moving Forward: A Call for Enhancement

This insight serves as a crucial piece of community knowledge, identifying a clear area for enhancement within ESHOPMAN's order management capabilities. Addressing this bug would significantly improve the user experience for merchants and operations teams relying on ESHOPMAN for their daily tasks. It underscores the ongoing collaborative effort within the ESHOPMAN community to refine and enhance the platform, ensuring it continues to deliver robust headless commerce solutions integrated with HubSpot CMS.