# Connecting Your Store to XoroERP — Setup, Sync & System Behavior ### 1. Overview This document provides a comprehensive guide to Shopify integration with XoroERP, covering connection setup, configuration requirements, permission management, and data synchronization processes. It explains how orders, customers, inventory, and financial data flow between Shopify and XoroERP, and defines the system behavior that governs transaction processing, inventory updates, and reporting alignment. The guide also outlines configuration validation procedures, operational constraints, testing requirements, and troubleshooting scenarios required to maintain stable synchronization and consistent ecommerce operations between both systems. *** ### 2. Integration Capabilities When configured correctly, the integration supports: * Automatic order import from Shopify into XoroERP * Customer record creation and validation * Inventory synchronization between systems * SKU and product data alignment * Financial reporting and reconciliation support * Shipment and fulfilment status updates *** ### 3. Functional Workflow #### 3.1 Integration Connection Flow * Shopify store connects to XoroERP using a supported connection method. * A secure authorization establishes controlled data exchange. * Orders created in Shopify are transmitted to XoroERP. * Customer and transaction data are validated. * Sales Orders are generated. * Inventory updates synchronize between systems. * Shipment confirmations update Shopify order status. * Financial records are generated based on ERP configuration. *** #### 3.2 Shopify Event → XoroERP System Behavior | **Shopify Event** | **Result in XoroERP** | | -------------------- | ---------------------------------- | | Order Created | Sales Order generated | | Order Updated | Record updated based on sync rules | | Fulfilment Completed | Shipment recorded | | Inventory Adjusted | Stock levels synchronized | | Payment Captured | Financial transaction recorded | *** #### 3.3 Shopify Integration Setup Workflow **Step 1: Store Identification** Before activation: * Confirm Shopify store URL * Confirm account name used in XoroERP * Confirm store time zone These values must be finalized before configuration. *** **Step 2: Authorization & Permission Granting** * Select connection method * Authorize required API scopes * Confirm all permissions are enabled Incomplete permissions may cause partial or failed synchronization. *** **Step 3: Configuration Validation** Validate: * Account name (permanent) * Time zone alignment * Required API permissions * SKU consistency across systems *** **Step 4: Testing Before Production** Testing should include: * Placing test orders in Shopify * Verifying order creation in XoroERP * Confirming inventory updates * Reviewing timestamps * Checking SKU mapping Testing prevents operational disruption. *** #### 3.4 Synchronization Processing Behavior * Synchronization runs automatically at configured intervals. * Orders are retrieved in batches but processed sequentially. * Sequential validation ensures data integrity. * Updates made in Shopify trigger synchronization updates in XoroERP. Sync Modes: * Real-time execution * Scheduled intervals * Manual trigger Higher synchronization frequency increases processing demand and should align with operational requirements. *** #### 3.5 Order Import Offset & Timing Control **Step 1: Configure Offset Duration** * Set delay (e.g., 20–35 minutes). **Step 2: Allow Order Stabilization** * Prevents repeated updates for high-volume stores. * Recommended for stores processing over 1,000 orders per day. *** #### 3.6 Daily Full Order Sync **Step 1: Trigger Daily Sync** * Imports all orders from previous day. **Step 2: Validate Order Recovery** * Used when order drops are suspected. * Does not update inventory. *** #### 3.7 Historical Order Import Control **Step 1: Define Integration Date** * Orders after this date auto-import. **Step 2: Handle Historical Orders** * Orders before this date must be manually imported: * Unfulfilled * Partially fulfilled **Step 3: Deposit Handling** * Opening balance account used for deposit mapping. * Auto-import must remain disabled during historical import. *** #### 3.8 Source of Transaction Authority * Shopify is the authoritative source for ecommerce transactions. * Orders, cancellations, and refunds originate in Shopify. * XoroERP reflects these changes for fulfilment and accounting. * Manual edits to Shopify-originated transactions in XoroERP may be overwritten during synchronization. * All operational edits should be performed in Shopify. *** ### 4. Core Configuration Logic #### 4.1 Shopify Connection Methods **A. App-Based Connection (Recommended)** * Installed directly within Shopify * Predefined permission scopes * Simplified onboarding * Lower risk of misconfiguration * Recommended for new implementations **B. API Token-Based Connection** * Manual credential generation * Manual permission configuration * Higher configuration responsibility * Used for legacy or existing environments Only one connection method should be active per store. *** #### 4.2 Required Configuration Elements | Configuration Item | Requirement | | --------------------- | --------------------------------------- | | Store Identification | Must be finalized before setup | | Account Name | Cannot be modified after setup | | Time Zone Alignment | Must match Shopify | | API Permissions | Must include required read/write access | | Inventory Access | Mandatory for stock synchronization | | Order Access | Required for transaction creation | | Financial Data Access | Required for reconciliation | Incorrect account name configuration requires full integration reconfiguration. *** #### 4.3 Critical Configuration Dependencies * Store identifier must be confirmed before setup. * Time zones must match for accurate reporting. * Required permissions must be granted. * SKU identifiers must match across systems. * Integration must be validated before production activation. *** #### 4.4 Required API Permission Scopes Essential permissions include: * Orders (read/write) * Inventory (read/write) * Payouts (if applicable) * Gift cards (if applicable) Inventory write permission is mandatory for stock synchronization. *** ### 5. Transaction-Level Behavior #### 5.1 Order Creation When a customer places an order in Shopify: * Order data is transmitted to XoroERP * Customer record is validated or created * Store mapping is applied * Line items are mapped to inventory records * Inventory allocation occurs * Pricing and tax values are recorded If SKU validation fails, order creation may be blocked until mapping is corrected. *** #### 5.2 Inventory Synchronization When inventory changes in XoroERP: * Updated quantities are pushed to Shopify * Stock levels update on storefront * Overselling risk is reduced If inventory write permission is disabled, updates fail. *** #### 5.3 Shipment Confirmation * Fulfilment recorded in XoroERP updates order status * Shipment details synchronize to Shopify *** #### 5.4 Financial Recording * Payment transactions are captured * ERP financial modules generate accounting entries * Shopify sales and payout data support reporting and reconciliation *** #### 5.5 Reporting Alignment Time zone consistency ensures: * Accurate revenue reporting * Correct daily totals * Reliable financial reconciliation *** #### 5.6 Error Handling Behavior If configuration or permissions are incomplete: * Orders may queue but fail validation * Orders may not import * Inventory updates may fail * Synchronization may be delayed *** ### 6. Failure Scenarios & Resolution Guidance **Scenario 1: Orders Not Syncing** **Possible causes** * Missing order permissions * Revoked authorization * Incorrect store mapping * SKU mapping errors **Resolution** * Reauthorize connection * Verify order permissions * Confirm store mapping * Validate SKU mapping *** **Scenario 2: Inventory Not Updating** **Possible causes** * Inventory write permission disabled * SKU mismatch * Inactive products * API errors **Resolution** * Enable inventory permissions * Verify SKU consistency * Confirm product status * Reauthorize connection *** **Scenario 3: Incorrect Order Dates or Reports** **Cause:** time zone mismatch\ **Resolution:** align Shopify and XoroERP time zones. *** **Scenario 4: Partial Data Sync** **Cause:** order permissions enabled but inventory permissions disabled.\ **Resolution:** enable inventory write permission. *** **Scenario 5: Connection Stops Working** **Possible causes** * App uninstalled * API credentials regenerated * Permission changes * Shopify API version updates **Resolution** * Reinstall or reauthorize connection * Validate credentials and scopes *** ### 7. Structured Examples **Example 1: Shopify Order Synchronization** Scenario: Customer places order in Shopify.\ System Impact: * Sales Order created * Customer validated or created * Inventory reduced * Payment recorded * Order available for fulfilment *** **Example 2: Inventory Update After Fulfilment** Scenario: Shipment confirmed in XoroERP.\ System Impact: * Shipment recorded * Shopify order marked fulfilled * Inventory updated across systems *** ### 8. Important Rules & Constraints * Store identifier and account name cannot be changed after configuration. * Time zones must align between systems. * Inventory write permission is mandatory. * Only one connection method should be active. * Shopify is the source of transaction changes. * Manual changes to Shopify-originated data in XoroERP are overwritten. * Integration must be validated before production use. *** ### 9. Best Practices * Use app-based connection for new implementations. * Validate permission scopes before activation. * Test integration using controlled scenarios. * Execute fulfilment from XoroERP as system of record. * Review synchronization logs regularly. * Perform transaction edits directly in Shopify. * Monitor sync frequency to balance performance and system load. *** ### 10. Common Mistakes / Pitfalls | **Situation** | **Result** | | --------------------------------- | ------------------------------------ | | Orders not appearing | Missing connection or permissions | | Inventory mismatch | Incorrect inventory sync settings | | Reporting discrepancies | Time zone misalignment | | Sync delays | Configuration or authorization issue | | Editing Shopify orders in XoroERP | Changes overwritten | | Missing API scopes | Partial synchronization failures | *** ### 11. Frequently Asked Questions (FAQs) #### **Which connection method is recommended for Shopify integration in XoroERP?** The **app-based connection** is recommended as it offers a simpler setup process and reduces the risk of configuration errors compared to manual API-based connections. *** #### **Can the store identifier or account name be changed after setup?** No, once the Shopify store is configured in XoroERP, the **store identifier and account name cannot be modified**. A new connection must be created if changes are required. *** #### **Why is it important to match the time zone with Shopify?** If the time zone is not aligned with Shopify, users may experience: * Incorrect order timestamps * Reporting inconsistencies * Data appearing under incorrect dates To ensure accurate reporting and synchronization, the time zone must match the Shopify store. *** #### **What happens if required API permissions are not granted?** If all required API permissions (scopes) are not provided: * Orders may fail to import * Inventory may not sync * Financial data may be incomplete Ensuring correct permissions during setup is critical for proper integration. *** #### **What happens if inventory write access is disabled?** If inventory write access is disabled: * XoroERP will not be able to update inventory in Shopify * Stock levels may become inaccurate * There is an increased risk of overselling *** #### **Can API-based and app-based connections be used together?** No, only **one connection method should be active at a time**. Using both simultaneously can lead to data conflicts and synchronization issues. *** #### **How frequently does Shopify data sync with XoroERP?** The synchronization frequency depends on system configuration and operational requirements. It may vary based on integration settings and business needs. *** #### **Why do some Shopify orders fail to sync into XoroERP?** Order sync failures may occur due to: * SKU mapping issues * Missing API permissions * Invalid or incomplete order data These areas should be reviewed during troubleshooting. *** #### **What are the most common causes of Shopify integration issues?** The most common causes include: * Missing API permissions * Inventory write access not enabled * Time zone mismatch These should be validated during setup and troubleshooting. *** #### **Should auto-import be enabled while importing historical Shopify orders?** No, auto-import should be disabled when importing historical orders, as enabling it may result in **duplicate order creation** in XoroERP. *** #### **What should be tested before going live with Shopify integration?** Before moving to production, users should verify: * Order import functionality * Inventory synchronization * Customer creation * Accurate timestamps * Proper SKU mapping This helps ensure the integration is functioning correctly. *** ### 12. Conclusion Following this guide ensures reliable Shopify integration setup, accurate configuration, and predictable system behavior between Shopify and XoroERP. Proper connection configuration, permission validation, synchronization monitoring, and troubleshooting practices ensure consistent order processing, accurate inventory updates, and reliable financial reporting. Adhering to these controls prevents data inconsistencies, synchronization failures, and operational disruption, supporting stable and scalable 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/connecting-your-store-to-xoroerp-setup-sync-and-system-behavior.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.