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)
Q1. Which connection method is recommended? A: App-based connection is recommended due to simplified setup and lower configuration risk.
Q2. Can the store identifier or account name be changed? A: No. These values are permanent after configuration.
Q3. Why must time zones match? A: To prevent reporting errors and timestamp inconsistencies.
Q4. What happens if API scopes are incomplete? A: Orders, inventory, or financial data may fail to synchronize.
Q5. What happens if inventory write access is disabled? A: Inventory updates fail and overselling risk increases.
Q6. Can API and app connections be used simultaneously? A: No. Only one connection method should be active.
Q7. How frequently does synchronization occur? A: Depends on configuration and operational requirements.
Q8. What should be tested before production? A: Order import, inventory updates, customer creation, timestamps, and SKU mapping.
Q9. Why do some orders fail to sync? A: SKU mapping errors, missing permissions, or invalid data.
Q10. What is the most common integration failure cause? A: Missing permissions, inventory write access disabled, or time zone mismatch.
Q11. Should auto-import be enabled when importing old orders? A: No, it can cause duplicate order imports.
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.
Last updated
Was this helpful?