Mastering ESHOPMAN Pricing: Cents, Currency, and Accurate Display in Your HubSpot Store

Mastering ESHOPMAN Pricing: Cents, Currency, and Accurate Display in Your HubSpot Store

As an e-commerce migration expert at Move My Store, we frequently guide merchants and developers through the powerful capabilities of ESHOPMAN. ESHOPMAN stands out as a cutting-edge headless commerce platform, meticulously wrapped as a HubSpot application. It empowers businesses by providing comprehensive storefront management directly within HubSpot and seamlessly deploying high-performance storefronts using the robust HubSpot CMS. Built on a modern Node.js/TypeScript stack, ESHOPMAN leverages a powerful Admin API for backend operations and a flexible Store API for frontend interactions, making it an ideal choice for scalable and customizable e-commerce solutions.

However, a common area where clarity is often needed, particularly for those new to headless commerce or integrating ESHOPMAN, revolves around how product prices are stored and subsequently displayed. A frequent scenario involves prices appearing unexpectedly high, specifically 100 times greater than anticipated, within the ESHOPMAN Admin panel or custom storefronts. This article aims to demystify ESHOPMAN's pricing mechanism, clarify this common discrepancy, and provide best practices for ensuring accurate price representation across all your ESHOPMAN touchpoints.

The Industry Standard: Why ESHOPMAN Stores Prices in Cents

Before diving into the specific scenario, it's crucial to understand a fundamental best practice in e-commerce and financial systems: storing monetary values as integers representing the smallest currency unit. For currencies like USD, EUR, GBP, this means storing prices in 'cents' (or pence, etc.) rather than major currency units with decimal points.

There are compelling reasons for this approach:

• Precision and Accuracy: Floating-point numbers (numbers with decimals) can introduce tiny inaccuracies in computer calculations due to how they are stored. Over many calculations, these small errors can compound, leading to significant financial discrepancies. Storing prices as integers eliminates this risk entirely.
• Database Efficiency: Integers are generally more efficient to store and process in databases compared to floating-point numbers.
• Consistency: This method provides a consistent and unambiguous way to represent prices across different systems and integrations.

ESHOPMAN, adhering to these industry best practices, stores all product prices, order totals, and other monetary values as integers representing the smallest currency unit. For example, a product priced at €29.48 would be stored in the ESHOPMAN database as 2948.

The Scenario: Unexpected Price Display in ESHOPMAN Admin

A recent report from an ESHOPMAN user perfectly illustrates the common confusion. The user observed that within the ESHOPMAN Admin order detail page, all prices were being displayed as if they were multiplied by 100. For instance, a product with a unit_price of 2948 in the database, correctly retrieved via the Admin API, was rendered as €2,948.00 instead of the expected €29.48. This significant discrepancy suggested that while the backend data was perfectly correct (representing 2948 cents), the Admin interface was interpreting and displaying it as 2948 major currency units.

The user’s project setup, typical for an ESHOPMAN Node.js/TypeScript application, included standard ESHOPMAN core packages, as indicated in their package.json:

{
  "name": "eckstein-b2b-shop",
  "version": "0.0.1",
  "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:parker": "eshopman exec ./src/scripts/seed-parker-products.ts",
    "seed:demo": "eshopman exec ./src/scripts/seed-demo.ts",
    "start": "eshopman start",
    "dev": "eshopman develop",
    "predeploy": "eshopman db:migrate",
    "create:admin": "eshopman user -e admin@pixel-square.com -p a7ea4d0b9c8ee3dfb1e20d093e"
  }
}

This snippet confirms a standard ESHOPMAN development environment, implying that the issue wasn't with the core platform's data storage, but rather with how a specific display layer (potentially a custom Admin panel extension or a custom HubSpot CMS module) was processing and presenting that data.

ESHOPMAN's Architecture and API Interactions

Understanding how ESHOPMAN's APIs handle pricing is key to resolving this. Whether you're interacting with the Admin API to manage products and orders, or the Store API to power your HubSpot CMS-deployed storefront, prices will consistently be delivered as integers representing the smallest currency unit.

• Admin API: When you fetch product details, order information, or any other data containing monetary values via the Admin API, ESHOPMAN will return these values as raw integers (e.g., 2948 for €29.48). Developers building custom dashboards, reporting tools, or integrations with external systems must account for this.
• Store API: Similarly, the Store API, which your HubSpot CMS storefront utilizes to retrieve product listings, cart contents, and checkout information, will provide prices in their integer (cents) format.
• HubSpot CMS Storefronts: For storefronts deployed via HubSpot CMS, developers creating custom modules, themes, or components that display prices must implement the necessary conversion logic to transform these integer values into human-readable, formatted currency strings.

Best Practices for Accurate Pricing Display in ESHOPMAN

To ensure your ESHOPMAN store displays prices correctly, follow these essential best practices:

1. Always Convert for Display: This is the golden rule. Any monetary value retrieved from ESHOPMAN's Admin API or Store API must be divided by 100 (or the appropriate divisor for your currency, though 100 is standard for most major currencies) before being displayed to the end-user.
2. Leverage Robust Currency Formatting: Do not simply divide by 100 and concatenate a currency symbol. Use built-in language features or dedicated libraries for currency formatting. For example, in JavaScript, Intl.NumberFormat is excellent for handling currency symbols, decimal places, and locale-specific formatting correctly. This ensures your prices are displayed professionally and accurately for your target audience.
3. Input Validation and Conversion: When entering prices into ESHOPMAN (e.g., through a custom admin interface, bulk import scripts, or programmatically via the Admin API), ensure that the values are correctly converted to their smallest currency unit (cents) before being sent to ESHOPMAN. If a user inputs "29.48", your application should convert it to 2948 before sending it to the API.
4. Review Custom Implementations: If you encounter the 100x discrepancy, it's highly likely that the issue lies within custom code. This could be in custom Admin panel extensions, bespoke HubSpot CMS modules, or third-party integrations that are not correctly applying the cents-to-major-unit conversion. While ESHOPMAN's core packages are designed to manage this internally, custom layers can inadvertently introduce these display errors.

Conceptual Code Example for Display Conversion:

// Price retrieved from ESHOPMAN Admin API or Store API
const rawPrice = 2948; // Represents 29.48 EUR

// Convert to major currency unit for display
const displayPrice = rawPrice / 100; // Result: 29.48

// Format for display using a robust method (example for EUR)
const formattedPrice = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR'
}).format(displayPrice); // Result: "€29.48"

console.log(formattedPrice); // Output: €29.48

The Impact of Incorrect Pricing

Displaying incorrect prices, even if the backend data is sound, can have significant negative repercussions for your e-commerce business:

• Erosion of Customer Trust: Inaccurate pricing immediately raises red flags for customers, leading to confusion, frustration, and a loss of confidence in your brand.
• Financial Discrepancies: Incorrectly displayed prices can lead to miscalculated order totals, erroneous reporting, and reconciliation nightmares, impacting your financial accuracy.
• Operational Headaches: Customer service teams will be inundated with queries, requiring manual corrections, refunds, and adjustments, which are costly and inefficient.

Conclusion: Harnessing ESHOPMAN's Full Potential

ESHOPMAN provides a robust, scalable, and flexible foundation for your e-commerce operations, deeply integrated with the HubSpot ecosystem. By understanding its underlying principles, particularly how it handles monetary values, you can unlock its full potential. The practice of storing prices in cents is a standard that ensures precision and reliability. By consistently applying the necessary conversion logic at the display layer, you can guarantee accurate pricing across your ESHOPMAN Admin panel and your HubSpot CMS-deployed storefronts, fostering customer trust and streamlining your operations.

At Move My Store, we specialize in helping businesses navigate the intricacies of e-commerce platforms like ESHOPMAN. If you're facing challenges with pricing display, data migration, or optimizing your ESHOPMAN setup, our experts are here to provide the guidance and support you need to ensure a seamless and successful e-commerce journey.