ESHOPMAN Admin API: Understanding 'updated_at' Behavior for Key Entities

Understanding 'updated_at' Behavior in ESHOPMAN: A Community Insight

In the ESHOPMAN community, a critical discussion has emerged regarding the behavior of the updated_at timestamp for certain entities when modified through the ESHOPMAN Admin API. Developers and merchants leveraging ESHOPMAN for their headless commerce storefronts deployed via HubSpot CMS rely on accurate timestamps for data synchronization, caching, and auditing. This insight delves into a specific scenario where the updated_at field may not reflect the latest modification time, providing clarity on its root cause and affected components.

The Challenge: Stale 'updated_at' Timestamps

When updating entities via the ESHOPMAN Admin API, such as altering a product variant's title or a store's name, the data itself updates correctly within the Node.js/TypeScript backend and PostgreSQL database. However, for a specific set of entities, the updated_at column remains unchanged, often mirroring the created_at value. This can lead to inconsistencies in data management and unexpected behavior in integrations or custom applications built around the ESHOPMAN Store API.

Affected ESHOPMAN Entities

Through community investigation, it has been identified that the following ESHOPMAN entities are impacted by this behavior:

• Product Variant: Updates to variants (e.g., title changes) do not refresh updated_at.
• Product Option: Modifications to product options also fail to update the timestamp.
• Price List: Changes to price list details leave the updated_at field static.
• Store: Updates to core store information (like the store name) similarly do not reflect in the timestamp.

Conversely, entities such as Product, Price, and Product Collection are NOT affected, as their update paths correctly trigger the necessary lifecycle hooks.

The Technical Root Cause: Bypassed Lifecycle Hooks

The core of this issue lies in how certain complex ESHOPMAN entities are updated internally. ESHOPMAN, built on Node.js/TypeScript, often utilizes an ORM (Object-Relational Mapper) like MikroORM for database interactions. For entities with intricate nested relationships (e.g., product variants with options, or stores with multiple currencies), ESHOPMAN's internal update logic employs a specific path:

upsertWithReplace() → upsertMany_() → nativeUpdateMany()

The critical step here is nativeUpdateMany(). This method, found in ESHOPMAN's internal data access layer, directly interacts with the database, bypassing MikroORM's entity lifecycle hooks. The onUpdate: () => new Date() hook, which is typically responsible for automatically updating the updated_at timestamp, never fires in this specific code path. Entities that use standard MikroORM .update() or wrap().assign() methods correctly trigger these hooks, hence their updated_at fields behave as expected.

Example Code Path (using Product Variant)

To illustrate the flow:

1. An Admin API call is made to update a product variant (e.g., POST /admin/products/:id/variants/:variant_id).
2. This triggers an ESHOPMAN workflow, leading to an update function for product variants.
3. Internally, productVariantService_.upsertWithReplace() is invoked.
4. This call then cascades to upsertMany_(), which ultimately uses the database driver's nativeUpdateMany().
5. The direct database operation in nativeUpdateMany() circumvents the ORM's entity lifecycle management, preventing the onUpdate hook from firing.

Implications for ESHOPMAN Developers and Merchants

While the data itself is updated, the frozen updated_at timestamp can impact:

• Caching Strategies: External caches relying on updated_at for invalidation might serve stale data.
• Integration Logic: Third-party integrations or webhooks triggered by updated_at changes might miss updates.
• Auditing and Reporting: Accurate historical data tracking becomes challenging.

For ESHOPMAN developers working with custom modules or integrations, understanding this behavior is crucial. It highlights the importance of being aware of the specific update mechanisms for different entity types within the ESHOPMAN Node.js/TypeScript backend. While the ESHOPMAN team is aware of such nuances, this community insight serves as a valuable heads-up for those building on the platform, especially when dealing with product variants, options, price lists, and store settings via the Admin API.