Ensuring Accurate Variant Data for ESHOPMAN Fulfillment Integrations

Ensuring Accurate Variant Data for ESHOPMAN Fulfillment Integrations

For ESHOPMAN merchants leveraging third-party fulfillment services like print-on-demand (POD) or dropshipping, accurate variant data is paramount. These providers often rely on specific variant metadata—such as a unique vendor SKU—to correctly process orders. A recent community discussion highlighted a critical gap where this essential data was not consistently available through the ESHOPMAN Admin API's fulfillment flow, leading to processing errors and integration headaches.

The Challenge: Missing Variant Metadata in Fulfillment Workflows

When an ESHOPMAN order was fulfilled via the Admin API (specifically through the createOrderFulfillmentWorkflow), fulfillment providers encountered an issue: they couldn't read per-line variant data, including crucial variant metadata. This meant that integrations designed to map ESHOPMAN product variants to vendor SKUs were failing, resulting in errors like 'Variant undefined is not mappable to a vendor SKU'.

Understanding the ESHOPMAN Core Flow Deep Dive

The community traced the root cause through ESHOPMAN's core flows (relevant to version 2.19.0 of the underlying framework):

• Incomplete Order Query: The create-fulfillment.ts workflow, which hydrates the order data, explicitly omitted items.variant.metadata from its query list. While other variant fields like SKU and weight were fetched, custom metadata was not.
• Data Flattening: During the prepareFulfillmentData step, order line items were flattened into a simplified structure containing only basic details like line_item_id, quantity, title, sku, and barcode. Any other variant data, even if fetched, was dropped here.
• Fulfillment Item Model Limitations: The fulfillment_item model itself does not include a direct variant relation or even a variant_id.
• Provider Isolation: Fulfillment providers receive these flattened fulfillment_item rows and the raw order object. Critically, providers operate within the fulfillment module's isolated container, lacking direct access to the full ESHOPMAN app's services (like product repositories or remote query capabilities) to fetch missing data independently.

The ESHOPMAN Solution & Best Practices

Fortunately, a straightforward solution and a crucial documentation clarification emerged from the discussion:

1. The One-Line Code Enhancement

The primary fix involves a minor but impactful change within the ESHOPMAN core flows. By adding "items.variant.metadata" to the field list in create-fulfillment.ts, the variant metadata becomes available within the order object passed to the provider:

--- a/packages/core/core-flows/src/order/workflows/create-fulfillment.ts
+++ b/packages/core/core-flows/src/order/workflows/create-fulfillment.ts
@@ fields: [
       "items.variant.material",
+      "items.variant.metadata",
       "items.variant_title",

This ensures that when the order object is passed to your custom fulfillment provider, order.items[].variant.metadata will be present.

2. Crucial Documentation Clarification for Providers

While the code change makes the data available, providers still need to know how to access it. Since the items argument to the provider is a list of simplified fulfillment_item records without variant data, providers must correlate data from the order object. The suggested best practice is:

The items argument is a list of fulfillment_item records. It carries line_item_id, quantity, title, sku and barcode only — it has no variant relation. To read variant data (including metadata), match item.line_item_id against order.items[].id and read the variant from the order.

3. Leveraging additional_data for Custom Per-Line Information

Another key insight from the discussion highlighted additional_data as a reliable channel for passing extra per-line data to a provider. This field, while not extensively documented, survives the data path and is accessible to providers. It's a robust option for custom information that doesn't fit into standard variant fields.

Conclusion for ESHOPMAN Developers

This community insight provides ESHOPMAN developers with a clear path to ensure robust and accurate fulfillment integrations, especially for scenarios involving complex variant data. By implementing the proposed code enhancement and adopting the recommended data access patterns, you can build more reliable dropshipping and print-on-demand solutions within your ESHOPMAN storefronts managed via HubSpot CMS.