Shopify → Xoro Product Import & Base Part Mapping
1. Overview
This guide explains how products are imported from Shopify into XoroERP, including sync direction control, base part identification methods, date-based import logic, field-level update protection, and product creation behavior. It defines how Shopify products are mapped, created, and maintained within XoroERP while preventing data overwrites and identifier conflicts.
2. Functional Workflow
2.1 Shopify → Xoro Product Import Flow
Step 1 — Configure Sync Direction
The system must be configured to pull products from Shopify into XoroERP using the appropriate import setting.
Step 2 — Define Required Configuration
Before import:
Item accounts must be configured.
Base part identification method must be selected.
Import date range must be defined.
Step 3 — Execute Initial Product Import
Xoro retrieves Shopify products based on product create date.
Items are automatically created in XoroERP.
Base part identifier is assigned.
Variants are generated automatically.
Step 4 — Post-Import Sync Behavior
After the initial import, product changes automatically sync from Shopify to Xoro.
System maintains mapping based on configured identifiers.
2.2 Product Sync Direction Control
Three product-related sync settings exist:
Sync Products
Xoro → Shopify
Push products from Xoro
Sync Prices
Xoro → Shopify
Push price updates
Pull Products
Shopify → Xoro
Import products from Shopify
Only the Pull Products setting controls Shopify → Xoro import.
Incorrect setting combinations may cause:
Data overwrites
Missed updates
Unexpected product creation
2.3 Initial Import Using Create Date
Product import is based strictly on Shopify product create date.
Required sequence:
Identify the oldest product create date in Shopify.
Define import date range.
Execute initial import.
After completion:
Future changes sync automatically.
Historical products outside the selected range are not imported.
2.4 Field-Level Update Protection Workflow
Field-level restrictions control whether Shopify updates can modify Xoro data.
If restrictions are enabled:
Selected fields remain unchanged in Xoro.
Shopify updates do not overwrite protected values.
Common protected fields include:
Item tags
Alternative item numbers
Manually maintained attributes
2.5 Product and Variant Creation Behavior
When importing a product:
Xoro item record is created automatically.
Base part identifier is assigned.
All variants are generated.
Variants are tightly linked to the product.
Variant removal limitations may prevent product deletion if cleanup is incomplete.
3. Core Configuration Logic
3.1 Base Part Identification Methods
Xoro requires a base part identifier to map Shopify products.
A. Product ID (Recommended)
Uses Shopify product ID.
System-generated and unique.
Lowest configuration risk.
B. Metafield Mapping
Uses custom Shopify metafield.
Requires client configuration in Shopify.
Must be unique per product.
C. Regular Expression (Regex)
Uses custom logic based on title, variants, or options.
Requires development validation.
Higher implementation risk.
Base part selection must be finalized before go-live.
3.2 Metafield Configuration Rules
Metafield mapping requirements:
Must exist in Shopify.
Must be unique per product.
Must follow specific format rules.
Format conversion requirement:
namespace.key
namespace,key
Failure to convert dot notation to comma notation results in sync failure.
3.3 Date-Based Import Constraint
The system:
Reads Shopify product create date only.
Does not evaluate update date.
Requires correct initial date range selection.
Incorrect date range leads to permanently missing products unless re-imported.
3.4 Field Update Restriction Settings
Field restrictions:
Protect master data in Xoro.
Prevent Shopify from overwriting selected fields.
Should be configured for environments with manual data maintenance.
3.5 Item Account Requirement
Item accounts must be defined prior to product import. Import cannot proceed without account configuration.
4. Transaction-Level Behavior
4.1 When a Product Is Imported
System behavior:
Creates new item record.
Assigns base part identifier.
Generates all variants.
Establishes Shopify mapping reference.
4.2 When Initial Import Completes
System behavior:
Enables automatic ongoing sync.
Updates mapped products based on identifier.
Maintains product linkage.
4.3 When Field Restrictions Are Enabled
System behavior:
Protected fields remain unchanged.
Shopify updates are ignored for restricted attributes.
4.4 When Metafield Mapping Fails
System impact:
Product import fails.
Mapping conflict occurs.
Sync may stop for affected records.
Common causes:
Incorrect namespace format
Duplicate metafield values
Missing metafield configuration
4.5 When Product Deletion Is Attempted
System behavior:
Product deletion may fail if variants exist.
Variant cleanup may be required before re-import.
5. Structured Examples
Example 1: Importing Historical Shopify Products
Action: Identify oldest Shopify product create date and execute initial import.
System Impact:
Products created in XoroERP.
Base part identifiers assigned.
Variants generated automatically.
Automatic future sync enabled.
Example 2: Using Metafield as Base Part Identifier
Action: Configure metafield mapping using namespace,key format.
System Impact:
Product matched using metafield value.
Mapping established for ongoing sync.
Import fails if value is not unique.
Example 3: Protecting Manual Data in Xoro
Action: Enable field-level update restriction for item tags.
System Impact:
Shopify updates ignored for protected fields.
Manual changes preserved.
Product mapping remains intact.
6. Important Rules & Constraints
Shopify → Xoro import works only on product create date.
Base part identifier must be defined before import.
Product ID is the safest identification method.
Metafields must be unique per product.
Shopify namespace.key must be converted to namespace,key.
Field restrictions prevent data overwrites.
Variants are automatically generated.
Variants may block product deletion.
Item accounts must exist before import.
Initial import date selection is critical and impacts all future sync behavior.
7. Best Practices
Finalize sync direction before enabling any settings.
Use Product ID unless advanced mapping is required.
Validate metafield format and uniqueness before import.
Configure field restrictions for manually maintained data.
Test metafield mapping using new products.
Define base part strategy during onboarding.
Select correct import date range during initial setup.
Coordinate regex-based logic with development teams.
8. Common Mistakes & Pitfalls
Incorrect product create date selected during initial import
Products are not imported into Xoro and remain missing
Non-unique metafield values used for base part identification
Product mapping conflicts or sync failures occur
Shopify metafield namespace entered using dot notation instead of comma format
Xoro does not recognize the metafield and import fails
Incorrect sync direction settings enabled
Unexpected overwrites or missing product updates
Product import enabled before defining item accounts
Product creation in Xoro fails
Field update restrictions not configured for protected fields
Shopify updates overwrite manually maintained Xoro data
Product deletion attempted while variants still exist
Product cannot be deleted or re-imported successfully
Regex-based base part logic configured without validation
Incorrect product identification and sync errors
Base part identification method changed after sync setup
Product mapping becomes inconsistent across systems
9. Frequently Asked Questions (FAQs)
Q1. Can Xoro pull products updated earlier in Shopify? A: No. Import works only on Shopify product create date.
Q2. What happens after the first product import? A: After initial import, product changes sync automatically.
Q3. Which base part method is safest? A: Product ID is the safest and simplest.
Q4. Can one metafield be used for all products? A: Yes, but values must be unique per product.
Q5. Why did metafield sync fail even though it existed? A: Because Shopify uses dot notation while Xoro requires comma notation.
Q6. Are variants created automatically? A: Yes. All variants are created during product import.
Q7. Can Shopify updates be prevented from overwriting Xoro data? A: Yes, by enabling field-level update restrictions.
Q8. Can regex be used without development involvement? A: No. Regex-based logic requires development validation.
10. Conclusion
Proper configuration of Shopify → Xoro product import ensures accurate product creation, reliable identifier mapping, and controlled data synchronization between systems. Defining the correct sync direction, selecting an appropriate base part identification method, and configuring field-level protections are critical to preventing duplication, data loss, and mapping conflicts.
Following the documented import workflow and configuration rules ensures stable product synchronization, consistent variant behavior, and long-term data integrity across Shopify and XoroERP environments.
Last updated
Was this helpful?