# 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. {% hint style="info" %} If multi-source publishing is not enabled, then products publish only to the default Shopify store. {% endhint %} *** #### 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 | Situation | Result / System Impact | | ------------------------------------------------------------------- | ---------------------------------------------------- | | 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.xorosoft.com/xoroerp-1/connected-apps/xoro-shopify-implementation-deep-dive/product-setup-import-and-inventory-synchronization/end-to-end-product-and-inventory-synchronization-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.