Safeguarding Your ESHOPMAN Store: Preventing Negative Order Totals

In the world of e-commerce, maintaining the integrity of financial data is paramount. For ESHOPMAN, our headless commerce platform seamlessly integrated with HubSpot, ensuring accurate order totals and ledger balances is critical for merchants managing their storefronts and deploying via HubSpot CMS.

A recent discussion within the ESHOPMAN developer community highlighted an important aspect of financial validation within the ESHOPMAN Admin API. This discussion focused on a potential scenario where draft orders could be created with negative unit prices, leading to significant financial discrepancies upon conversion to live orders.

The Challenge: Negative Unit Prices in Draft Orders

The core of the issue revolved around the validation schema for item unit prices within the ESHOPMAN Admin API. Specifically, when creating or updating draft order items, the existing validation for unit_price allowed for negative values. While seemingly a minor detail, this could have profound implications:

• Corrupted Financial Records: A draft order item with a unit_price of, for example, -500, would result in a live order where the store effectively 'owes' money to the buyer for merchandise purchased.
• Accounting Vulnerability: This could lead to incorrect order totals, item totals, and overall accounting balances, creating a severe financial and accounting vulnerability for businesses.
• Rogue Integrations: Malicious or misconfigured third-party integrations interacting with the Admin API could exploit this to generate fraudulent orders.

Technical Deep Dive: Unbounded Unit Price Validation

The root cause was identified in the Node.js/TypeScript validation schemas used by the ESHOPMAN Admin API. In the definition for draft order items, the unit_price field, which utilizes a BigNumberInput, lacked an explicit lower-bound check. This meant that any number, including negative ones, could be accepted.

Consider the simplified (adapted) schema structure:

const Item = z.object({
  // ... other fields ...
  variant_id: z.string().nullish(),
  unit_price: BigNumberInput.nullish(), // <-- Unbounded!
  quantity: z.number(),
  metadata: z.record(z.string(), z.unknown()).nullish(),
})

Similarly, in update operations, a simple z.number().nullish() was used, also without a .min(0) constraint.

The Solution: Implementing Non-Negative Validation

To address this, a robust solution was proposed to enforce non-negative values for all unit prices. This involves two key steps within the ESHOPMAN Admin API's validation logic:

1. Introducing NonNegativeBigNumberInput

A new validation type, NonNegativeBigNumberInput, was suggested to extend the existing BigNumberInput. This new type refines the input to ensure its value is always greater than or equal to zero.

export const N
  (val) => {
    if (typeof val === "number") return val >= 0
    if (typeof val === "string") return !val.trim().startsWith("-") && Number(val) >= 0
    if (typeof val === "object" && val !== null && "value" in val) {
      return !String(val.value).trim().startsWith("-") && Number(val.value) >= 0
    }
    return true
  },
  { message: "unit_price must be greater than or equal to 0" }
)

2. Applying the Guard to Draft Order Item Validators

Once defined, this new validation type is applied to the relevant schemas for draft order items. This ensures that any attempt to create or update an item with a negative unit price will be rejected by the API.

// ... imports ...
import {
  // ... other validators ...
  BigNumberInput,
  NonNegativeBigNumberInput,
} from "../../utils/common-validators"

// ... in the Item schema ...
const Item = z.object({
  // ... other fields ...
  variant_id: z.string().nullish(),
  unit_price: NonNegativeBigNumberInput.nullish(), // <-- Now guarded!
  quantity: z.number().gt(0),
  metadata: z.record(z.string(), z.unknown()).nullish(),
})

// ... in update operations ...
export const AdminUpdateDraftOrderItem = z.object({
  quantity: z.number().gt(0),
  unit_price: z.number().min(0).nullish(), // <-- Now guarded!
  compare_at_unit_price: z.number().min(0).nullish(),
})

ESHOPMAN's Commitment to Robust Commerce

This community insight underscores ESHOPMAN's commitment to building a secure and financially sound headless commerce platform. The proactive identification and proposed resolution of such vulnerabilities by the ESHOPMAN community and development team ensure that merchants can confidently manage their storefronts, knowing that their financial data is protected. For developers extending ESHOPMAN via the Admin API, this highlights the importance of rigorous input validation, especially for sensitive financial fields.