Preserving Historical Order Data: ESHOPMAN's Approach to Order Total Recalculations Post-Return
Understanding ESHOPMAN's Order Total Recalculations Post-Return
Accurate historical order data is paramount for any e-commerce operation, especially when managing returns and refunds. For ESHOPMAN merchants and developers leveraging the platform's robust Node.js/TypeScript backend and HubSpot CMS integration, understanding how order totals are handled after a return is crucial for maintaining data integrity and ensuring transparency for both customers and internal reporting.
A key observation within the ESHOPMAN community highlights a specific behavior during the return process: when items are received as part of a return, certain 'original' fields within the order object are unexpectedly overwritten. This can lead to a loss of the 'point-in-time' data, making it challenging to accurately reflect the order's initial value after a return has been processed.
The Challenge: Overwriting of Original Order Fields
The issue arises when a return is performed on an order, for instance, returning one out of two purchased items. The act of 'Receiving Items' triggers a recalculation of order totals. During this update, fields intended to capture the original state of the order, such as original_total, original_tax_total, and line-item original_subtotal, are updated to reflect the new, post-return values. This overwrites the true original purchase data.
Ideally, the original_* fields should remain immutable, preserving the values from when the order was first placed. Concurrently, fields like total, subtotal, and tax_total should dynamically update to reflect the current state of the order after any adjustments, such as returns. This distinction is vital for displaying both an 'Original Total' and a 'Current Total' in customer-facing interfaces or ESHOPMAN's HubSpot admin dashboards.
Technical Details and Evidence
The observed behavior indicates that upon receiving a return, the order's version increments, and the top-level original_* fields, along with line-item original_subtotal, become synchronized with their current counterparts. While the summary.original_order_total field appears to correctly retain the initial order value, the primary order properties and line-item properties lose their original context.
Below is an example of a typical ESHOPMAN project's package.json, illustrating the core dependencies:
{ "name": "xxx", "version": "0.0.2", "description": "A starter for ESHOPMAN projects.", "author": "ESHOPMAN (https://eshopman.com)", "license": "MIT", "keywords": [ "sqlite", "postgres", "typescript", "ecommerce", "headless", "eshopman" ], "scripts": { "build": "eshopman build", "seed": "eshopman exec ./src/scripts/seed.ts", "seed:categories": "eshopman exec ./src/scripts/seed-categories.ts", "start": "eshopman start", "dev": "eshopman develop", "docker:up": "docker compose up --build -d", "docker:down": "docker compose down", "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 --runInBand --forceExit", "test:unit": "TEST_TYPE=unit NODE_OPTI jest --silent --runInBand --forceExit" }, "dependencies": { "@eshopman/admin-sdk": "2.12.3", "@eshopman/cli": "2.12.3", "@eshopman/framework": "2.12.3", "@eshopman/eshopman": "2.12.3", "pg": "^8.13.0" }, "devDependencies": { "@eshopman/test-utils": "2.12.3", "@swc/core": "1.7.28", "@swc/jest": "^0.2.36", "@types/jest": "^29.5.13", "@types/node": "^20.0.0", "jest": "^29.7.0", "prop-types": "^15.8.1", "react": "^18.2.0", "react-dom": "^18.2.0", "ts-node": "^10.9.2", "typescript": "^5.6.2", "vite": "^5.2.11", "yalc": "^1.0.0-pre.53" }, "engines": { "node": ">=20" }}Consider an order with an original total of 48.279. After returning one item, the original_total field is updated to 24.1395, losing the initial record. The same behavior is seen in line items, where original_subtotal changes from 45.98 to 22.99.
Order Totals Before Return:
{ "id": "order_01KEF9P2SK1EZRFWMSYTM5KWTC", "status": "completed", "created_at": "2026-01-08T17:15:19.732Z", "canceled_at": null, "email": null, "display_id": 3674, "custom_display_id": "X4DLUNX4", "currency_code": "cad", "metadata": null, "total": 48.279, "credit_line_total": 0, "item_subtotal": 45.98, "item_total": 48.279, "item_tax_total": 2.299, "original_item_tax_total": 2.299, "item_discount_total": 0, "shipping_subtotal": 0, "original_total": 48.279, "original_tax_total": 2.299, "subtotal": 45.98, "discount_total": 0, "discount_subtotal": 0, "shipping_total": 0, "shipping_tax_total": 0, "original_shipping_tax_total": 0, "shipping_discount_total": 0, "tax_total": 2.299, "summary": { "paid_total": 48.279, "raw_paid_total": { "value": "48.279", "precision": 20 }, "refunded_total": 0, "accounting_total": 48.279, "credit_line_total": 0, "transaction_total": 48.279, "pending_difference": 0, "raw_refunded_total": { "value": "0", "precision": 20 }, "current_order_total": 48.279, "original_order_total": 48.279, "raw_accounting_total": { "value": "48.279", "precision": 20 }, "raw_credit_line_total": { "value": "0", "precision": 20 }, "raw_transaction_total": { "value": "48.279", "precision": 20 }, "raw_pending_difference": { "value": "0", "precision": 20 }, "raw_current_order_total": { "value": "48.279", "precision": 20 }, "raw_original_order_total": { "value": "48.279", "precision": 20 } }, "version": 6, "region_id": "reg_01K83W6J8C3PMG7JTA9FXC1ARH", "items": [ { "id": "ordli_01KEF9Q9MNMZE6XEQB5V6P8TM6", "requires_shipping": false, "is_giftcard": false, "is_discountable": true, "is_tax_inclusive": false, "is_custom_price": false, "metadata": {}, "raw_compare_at_unit_price": null, "raw_unit_price": { "value": "22.99", "precision": 20 }, "created_at": "2026-01-08T17:15:59.509Z", "updated_at": "2026-01-08T17:15:59.509Z", "deleted_at": null, "tax_lines": [ { "id": "ordlitxl_01KEF9Q9NTCFY2XHJH30CYDHSF", "description": "GST", "tax_rate_id": "txr_01K83W6JA4RVP89ABZW1JTJVVG", "code": "GST", "provider_id": "system", "item_id": "ordli_01KEF9Q9MNMZE6XEQB5V6P8TM6", "raw_rate": { "value": "5", "precision": 20 }, "created_at": "2026-01-08T17:15:59.546Z", "updated_at": "2026-01-08T17:15:59.546Z", "deleted_at": null, "rate": 5, "total": 2.299, "subtotal": 2.299, "raw_total": { "value": "2.299", "precision": 20 }, "raw_subtotal": { "value": "2.299", "precision": 20 } } ], "adjustments": [], "compare_at_unit_price": null, "unit_price": 22.99, "quantity": 2, "raw_quantity": { "value": "2", "precision": 20 }, "detail": { "id": "orditem_01KEF9TRPQF0TJS937HQK43B0K", "version": 6, "metadata": null, "order_id": "order_01KEF9P2SK1EZRFWMSYTM5KWTC", "raw_unit_price": { "value": "22.99", "precision": 20 }, "raw_compare_at_unit_price": null, "raw_quantity": { "value": "2", "precision": 20 }, "raw_fulfilled_quantity": { "value": "2", "precision": 20 }, "raw_delivered_quantity": { "value": "2", "precision": 20 }, "raw_shipped_quantity": { "value": "0", "precision": 20 }, "raw_return_requested_quantity": { "value": "0", "precision": 20 }, "raw_return_received_quantity": { "value": "0", "precision": 20 }, "raw_return_dismissed_quantity": { "value": "0", "precision": 20 }, "raw_written_off_quantity": { "value": "0", "precision": 20 }, "created_at": "2026-01-08T17:17:53.243Z", "updated_at": "2026-01-08T17:17:53.243Z", "deleted_at": null, "item_id": "ordli_01KEF9Q9MNMZE6XEQB5V6P8TM6", "unit_price": 22.99, "compare_at_unit_price": null, "quantity": 2, "fulfilled_quantity": 2, "delivered_quantity": 2, "shipped_quantity": 0, "return_requested_quantity": 0, "return_received_quantity": 0, "return_dismissed_quantity": 0, "written_off_quantity": 0 }, "subtotal": 45.98, "total": 48.279, "original_subtotal": 45.98, "original_total": 48.279, "discount_subtotal": 0, "discount_tax_total": 0, "discount_total": 0, "tax_total": 2.299, "original_tax_total": 2.299, "refundable_total_per_unit": 24.1395, "refundable_total": 48.279, "fulfilled_total": 48.279, "shipped_total": 0, "return_requested_total": 0, "return_received_total": 0, "return_dismissed_total": 0, "write_off_total": 0, "raw_subtotal": { "value": "45.98", "precision": 20 }, "raw_total": { "value": "48.279", "precision": 20 }, "raw_original_subtotal": { "value": "45.98", "precision": 20 }, "raw_original_total": { "value": "48.279", "precision": 20 }, "raw_discount_subtotal": { "value": "0", "precision": 20 }, "raw_discount_tax_total": { "value": "0", "precision": 20 }, "raw_discount_total": { "value": "0", "precision": 20 }, "raw_tax_total": { "value": "2.299", "precision": 20 }, "raw_original_tax_total": { "value": "2.299", "precision": 20 }, "raw_refundable_total_per_unit": { "value": "24.1395", "precision": 20 }, "raw_refundable_total": { "value": "48.279", "precision": 20 }, "raw_fulfilled_total": { "value": "48.279", "precision": 20 }, "raw_shipped_total": { "value": "0", "precision": 20 }, "raw_return_requested_total": { "value": "0", "precision": 20 }, "raw_return_received_total": { "value": "0", "precision": 20 }, "raw_return_dismissed_total": { "value": "0", "precision": 20 }, "raw_write_off_total": { "value": "0", "precision": 20 } } ]}Order Totals After Return:
{ "id": "order_01KEF9P2SK1EZRFWMSYTM5KWTC", "status": "completed", "created_at": "2026-01-08T17:15:19.732Z", "canceled_at": null, "email": null, "display_id": 3674, "custom_display_id": "X4DLUNX4", "currency_code": "cad", "metadata": null, "total": 24.1395, "credit_line_total": 0, "item_subtotal": 22.99, "item_total": 24.1395, "item_tax_total": 1.1495, "original_item_tax_total": 1.1495, "item_discount_total": 0, "shipping_subtotal": 0, "original_total": 24.1395, "original_tax_total": 1.1495, "subtotal": 22.99, "discount_total": 0, "discount_subtotal": 0, "shipping_total": 0, "shipping_tax_total": 0, "original_shipping_tax_total": 0, "shipping_discount_total": 0, "tax_total": 1.1495, "summary": { "paid_total": 48.279, "raw_paid_total": { "value": "48.279", "precision": 20 }, "refunded_total": 0, "accounting_total": 24.1395, "credit_line_total": 0, "transaction_total": 48.279, "pending_difference": -24.1395, "raw_refunded_total": { "value": "0", "precision": 20 }, "current_order_total": 24.1395, "original_order_total": 48.279, "raw_accounting_total": { "value": "24.1395", "precision": 20 }, "raw_credit_line_total": { "value": "0", "precision": 20 }, "raw_transaction_total": { "value": "48.279", "precision": 20 }Implications for ESHOPMAN Users
This behavior has significant implications for ESHOPMAN merchants and developers:
- Reporting Accuracy: Loss of original transaction values can skew historical sales reports and make it difficult to reconcile initial order values with current states.
- Customer Transparency: Displaying an 'original total' on customer order pages or in HubSpot-managed customer portals would be inaccurate if these fields are overwritten.
- Accounting and Auditing: Maintaining a clear, immutable record of the original purchase price is crucial for accounting practices and audit trails.
- Custom Development: Developers building custom features or integrations with ESHOPMAN's Admin API need to be aware of this behavior when querying order data and rely on fields like
summary.original_order_totalfor the true initial value.
While the summary.original_order_total provides a reliable source for the initial order value, the inconsistency across other 'original' fields requires careful consideration in ESHOPMAN implementations. This insight serves as a crucial piece of community knowledge for ensuring robust and accurate order management within the ESHOPMAN ecosystem.