End-to-End Product & Inventory Synchronization Guide
1. Overview
This document provides a comprehensive guide to product synchronization, handle-based product identification, pricing behavior, and inventory management between XoroERP and Shopify. It explains how products are created, matched, and updated across systems, how pricing and product data are controlled, and how inventory accuracy is maintained through configuration, tagging, and synchronization workflows.
2. Functional Workflow
2.1 Product Sync Direction & Source of Truth
Product synchronization can operate in either direction.
Xoro → Shopify
Products are created and managed in XoroERP
Xoro acts as the system of record
Product data is exported to Shopify
Shopify → Xoro
Products originate in Shopify
Product data is imported into XoroERP
Sync direction must be finalized during onboarding to ensure consistent product ownership and prevent conflicts.
2.2 Product Creation & Sync from Xoro to Shopify
Step 1 — Product Creation in XoroERP Product is created with required item details and tags.
Step 2 — System-Generated Identifiers
Product handle is automatically generated by the system unless manually defined during product creation
Variants created from option codes
Product enters pending sync queue
Step 3 — Sync to Shopify
If sync settings and tagging criteria are met:
Product exported to Shopify
Variants created automatically
Sync completes under normal processing conditions
Pending queue status is expected during processing.
2.3 Product Identification & Handle Matching Workflow
Step 1 — Product Identification
Products matched using product handle
SKU or item number is not the primary identifier
Step 2 — Handle Validation
Each product must have a valid handle
Missing or incorrect handles create duplicates
Step 3 — Ongoing Updates
Handles must remain unchanged after synchronization begins
Updates rely on handle matching
2.4 Initial Product Upload & Handle Reconciliation (Onboarding Existing Stores)
If products already exist in Shopify:
Download product data from Shopify
Export products from XoroERP
Match using item number + handle
Update missing handles
Re-upload product file
Repeat verification before go-live
This prevents duplicate product creation.
2.5 Product Configuration (Variant vs Non-Variant)
Variant Products
Use attributes such as size or color
Managed at option level
Non-Variant Products
Fields managed at item level
Handles and titles editable
Full field visibility supported
Product structure must be defined before configuration.
2.6 Product Price Synchronization
Two mechanisms control pricing.
Upload Item Prices (Recommended)
Matches by item number
Bulk price updates
No handle dependency
Updates Shopify pricing directly
Product Upload
Used for metadata updates
Does not update pricing
Zero-price protection prevents accidental price overwrites
2.7 Field-Level Product Sync
Only selected fields sync:
Price
Cost
Weight
Images
Active status
Product options
Unselected fields remain unchanged.
2.8 Inventory Synchronization Workflow
Inventory sync is item-based (not handle-based) and operates in stages.
Stage 1 — Initial Inventory Sync
Full baseline alignment
Required before go-live
Stage 2 — Delta Sync
Continuous updates
Works only after initial sync
Before running inventory sync:
Ensure all orders are synced
Confirm accurate ATS in XoroERP
Inventory sync overwrites Shopify quantities and assumes XoroERP inventory is accurate. It does not validate pending Shopify orders before updating stock levels.
2.8.1 Weekly vs Daily Inventory Sync Strategy
Daily Sync Behavior May overwrite valid inventory when orders are pending.
Weekly Sync Recommendation Provides buffer for resolving discrepancies before inventory correction.
2.8.2 ATS Validation Requirement
Before enabling scheduled inventory synchronization (daily or weekly), a full inventory baseline must be validated.
Step 1 — Execute Full Inventory Sync
Complete a full inventory sync to establish quantity alignment between XoroERP and Shopify.
Step 2 — Validate Available-to-Sell (ATS) Accuracy
Client must confirm that On-hand, Reserved, and Available-to-Sell quantities are accurate.
Step 3 — Enable Scheduled Sync
Only after ATS validation is confirmed should daily or weekly sync be activated.
2.9 Manual Inventory Sync Process
Manual sync is required only when new tagged items are added.
Before running manual sync:
Check inventory queue
Resolve pending entries
Confirm no active processing
Running during pending operations causes duplicate updates.
2.10 Inventory Sync Modes
Full Sync
Overwrites all quantities
Used at go-live or major discrepancy only
Daily Sync (Recommended)
Keeps systems aligned
Run during off-peak hours
Weekly Sync
Used when order ingestion delays occur
2.11 Multi-Store & Multi-Source Product Publishing
Multi-Store Product Handling
Same product may exist across multiple stores
Each store may use a different handle
Handles stored as comma-separated values
System checks sequentially
Multi-Source Publishing Within a Single Shopify Account
When a Shopify account supports multiple operational sources (e.g., POS, E-commerce, Web, B2B):
Step 1 — Enable Multi-Source Publishing Setting Activate configuration allowing product publishing to multiple Shopify sources.
Step 2 — Define Target Sources Confirm whether products must appear in:
POS
E-commerce
Web
B2B
Step 3 — Validate Product Visibility After publishing, verify that products appear in all required Shopify sources.
If multi-source publishing is not enabled, then products publish only to the default Shopify store.
2.12 SKU Tag-Based Store Filtering
Tags control which SKUs sync
Reduce processing load
Do not identify products
Do not replace handles
2.13 Multi-Account Inventory Control
If multiple Shopify accounts use the same store URL:
Only one account pushes inventory
Others must be restricted
Prevents double deduction and inventory drift.
2.14 Inventory Change Logs & Monitoring
Provides visibility into:
ATS changes
Sync discrepancies
Missed updates
Duplicate updates
Supports troubleshooting.
3. Core Configuration Logic
3.1 Product Sync Configuration
Controls product export to Shopify
Uses handle matching
Requires defined sync direction
3.2 Price Sync Configuration
Controls price updates
Can run independently of product sync
Incorrect setup may cause duplicates or missed updates
3.3 Handle Management
Primary product identifier
Missing or changed handles create duplicates
Must never change after sync
3.4 Inventory Tracking Setting
Track Quantity controls inventory behavior
Required for sync
Disabled tracking prevents stock updates
3.5 Inventory Sync Settings
Full, daily, weekly modes available
XoroERP assumed system of record
3.6 Multi-Store Handle Configuration
Supports multiple handles per product
Ensures store-specific matching
3.7 Tag-Based Filtering
Controls SKU sync scope
Improves performance
4. Transaction-Level Behavior
4.1 When Product Sync Runs
Product matched using handle
Created or updated in Shopify
Duplicate created if handle missing
4.2 When New Product Is Created
Handle auto-generated
Variants created
Product enters queue
Exported if eligible
4.3 When Price Updates Run
Upload Item Prices updates price
Product upload does not change price
Zero values may overwrite pricing
4.4 When Inventory Sync Runs
Quantities read from XoroERP
Shopify quantities overwritten
Assumes XoroERP accuracy
4.5 Inventory Sync With Pending Orders
ATS becomes inaccurate
Overselling risk increases
4.6 Manual Sync During Pending Queue
Duplicate updates
Incorrect stock
Sync inconsistencies
4.7 Tracking Disabled
Item treated as non-inventory
Stock does not sync
5. Structured Examples
Initial Product Upload Handles reconciled → prevents duplication.
Bulk Price Update Pricing updated without handle dependency.
New Product Creation Handle auto-generated → product exported.
Inventory Sync Before Orders Imported Inventory overwritten → ATS inaccurate.
Manual Inventory Sync With Pending Queue Duplicate inventory updates.
Multi-Store Product Sync Multiple handles ensure correct matching.
6. Important Rules & Constraints
Handle is primary product identifier
Modifying handles creates duplicates
Product upload does not update prices
Inventory sync is item-based
Initial sync required before delta
Full sync only for go-live
Inventory overwrites Shopify values
Only one account should push inventory
All orders must sync before inventory sync
7. Best Practices
Maintain XoroERP as source of truth
Never modify handles
Reconcile handles during onboarding
Enable zero-price protection
Enable Track Quantity
Run daily inventory sync
Resolve pending logs first
Define tagging strategy
Restrict duplicate inventory accounts
8. Common Mistakes & Pitfalls
Missing handle reconciliation during onboarding
Duplicate products created in Shopify
Using SKU instead of handle for product matching
Product updates fail or create duplicate products
Zero-price protection disabled during price sync
Shopify product prices overwritten with zero values
Running inventory sync before initial baseline sync
Inventory becomes inaccurate and ATS miscalculates
Running inventory sync before all orders are synced
Incorrect stock levels and overselling risk
Running manual inventory sync while queue has pending entries
Duplicate inventory updates and incorrect quantities
Ignoring multi-store handle requirements
Product mismatch across Shopify stores
Allowing multiple Shopify accounts to push inventory simultaneously
Inventory duplication or drift
Connecting Shopify after product upload without reconciliation
Duplicate product creation
Running full inventory sync repeatedly
Unnecessary inventory overwrites
9. Frequently Asked Questions (FAQs)
Q1. What is a product handle and why is it important?
A: The product handle is the primary identifier used to match products between XoroERP and Shopify. If a handle is missing or changed, Shopify creates a new product instead of updating the existing one.
Q2. Is SKU the same as a product handle?
A: No. SKU is used mainly for inventory and price operations. Product matching relies on the handle.
Q3. When must product handles be reconciled?
A: Product handles can be reconciled in the following case
During initial product upload
When onboarding an existing store
Before go-live
When Shopify is connected after products already exist
Handles must never be modified after synchronization begins.
Q4. How are products created and synced from XoroERP?
A: Products are created and synced from XoroERP in the following order:
System generates handle automatically
Variants created from option codes
Product enters pending queue
Exported if sync criteria are met
Q5. How are product prices updated?
A: Using Upload Item Prices module. Product uploads do not update pricing.
Q6. How does inventory synchronization work?
A: Initial sync establishes baseline. Delta sync updates continuously. XoroERP inventory overwrites Shopify.
Q7. What happens if inventory sync runs before orders are synced?
A: ATS becomes inaccurate and overselling risk increases.
Q8. Can one product exist in multiple stores?
A: Yes. Multiple handles can be configured per store.
Q9. What configuration settings are critical?
A: The following configuration settings are critical:
Correct sync direction
Valid handle matching
Zero-price protection
Track Quantity enabled
Initial inventory sync completed
Proper tagging strategy
Restricted duplicate inventory accounts
Q10. When should daily full order sync be enabled? A: Only when orders are suspected to be missed.
Q11. Why is weekly inventory sync preferred? A: It avoids inventory correction issues with pending orders.
10. Conclusion
Following these product synchronization, pricing control, and inventory management procedures ensures accurate product matching, reliable pricing updates, and consistent inventory levels across Shopify and XoroERP. Proper handle management and controlled synchronization workflows prevent duplicate products, pricing inconsistencies, and stock discrepancies while supporting stable ecommerce operations.
Last updated
Was this helpful?