Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

PreviousXoro Shopify Implementation Deep DiveNextManaging Orders, Refunds & Exchanges in XoroERP

Last updated

Was this helpful?