Data Synchronization Between Multiple ERPNext Sites

Data synchronization between multiple ERPNext sites is an architectural decision, not a configuration feature. It defines how independent ERP installations exchange information while preserving transactional integrity, auditability, and legal isolation.

This document explains how multi-site synchronization works internally, why naïve synchronization designs fail, and how ERPNext must be extended to support controlled data propagation without violating system guarantees.

The focus is on internal behavior, data ownership, transaction safety, and governance — not interface navigation or user instructions.

1. Concept of Multi-Site Architecture in ERPNext

An ERPNext site represents a fully isolated system boundary. Each site has its own database, file storage, background workers, scheduler, and authentication context.

Unlike multi-company setups, which share a database, multi-site architecture introduces physical data separation. No data is shared by default, and no implicit relationship exists between sites.

Synchronization therefore becomes an external orchestration problem, not a native ERP behavior.

Conceptual Architecture Flow

Independent ERPNext sites
→ Separate databases
→ Independent ledgers
→ Controlled integration layer

Site Boundary Characteristics

Aspect	Behavior
Database	Fully isolated per site
Users and roles	Local to each site
Transactions	Never cross site boundary
Audit trail	Site-specific

Core Principle

• A site is a hard system boundary
• No implicit trust exists between sites
• Synchronization must be explicit and traceable

2. Business and Legal Drivers for Multi-Site Synchronization

Multi-site synchronization is required when organizational, legal, or operational constraints prevent the use of a single ERP instance.

ERPNext is often deployed across multiple sites due to regulatory isolation, regional autonomy, data residency laws, or performance requirements.

Synchronization exists to enable visibility and coordination, not to merge systems.

Decision Evaluation Flow

Separate legal environments?
→ Separate ERP deployments?
→ Central visibility required?
→ Controlled synchronization needed

Common Multi-Site Scenarios

Scenario	Driver
Country-wise ERP deployments	Tax and compliance isolation
Franchise networks	Operational independence
High-volume operations	Performance separation

Governance Rule

• Do not sync sites to compensate for bad design
• Each site must remain operationally independent
• Synchronization must never blur legal ownership

3. ERPNext Site Isolation vs Company Isolation

A common architectural mistake is treating multi-site synchronization as an extension of multi-company behavior.

In ERPNext, multi-company separation exists within a shared database, while multi-site separation exists at the infrastructure level. The guarantees and risks are fundamentally different.

Synchronization logic must therefore assume zero shared state.

Isolation Comparison Flow

Multi-company
→ Shared database
→ Logical isolation

Multi-site
→ Separate databases
→ Physical isolation

Isolation Comparison

Dimension	Multi-Company	Multi-Site
Database	Shared	Separate
Ledger isolation	Logical	Physical
Synchronization	Not required	Mandatory
Failure impact	Local	Cross-system

Design Implication

• Company logic cannot be reused for site sync
• Each site must validate data independently
• Trust boundaries must be explicit

4. Classification of Data for Synchronization

Not all ERPNext data is suitable for synchronization. Data must be classified based on ownership, mutability, and audit sensitivity before any synchronization logic is implemented.

Blind synchronization of transactional data creates reconciliation risks, duplicate postings, and legal ambiguity.

Data Classification Flow

Data identified
→ Ownership evaluated
→ Mutability assessed
→ Sync eligibility determined

ERPNext Data Categories

Data Type	Sync Suitability
Item master	High
Customer and supplier	Medium
Stock ledger	Not recommended
GL entries	Never

Governance Principle

• Masters may be synchronized
• Transactions should be referenced, not copied
• Ledgers must never be synchronized

5. Synchronization Boundary and Ownership Rules

Every synchronization design must define a clear source of truth. Without ownership rules, conflicts become inevitable and resolution becomes arbitrary.

ERPNext does not provide built-in conflict resolution across sites. Ownership must be defined at design time, not at runtime.

Ownership Resolution Flow

Record created
→ Owning site identified
→ Write access restricted
→ Other sites consume read-only

Ownership Models

Model	Behavior
Single source of truth	One site owns, others consume
Distributed ownership	High conflict risk
Federated ownership	Domain-specific control

Non-Negotiable Rule

• No record should be writable from multiple sites
• Conflict resolution must not rewrite history
• Audit trail must identify originating site

6. Source-of-Truth Design Model in Multi-Site Synchronization

A source-of-truth model defines which ERPNext site owns the authoritative version of a specific data entity. Without this definition, synchronization degenerates into conflict resolution, which ERPNext is not designed to handle natively.

Ownership must be decided per data domain, not globally. Different sites may own different masters, but no single record should ever have multiple owners.

This model enforces deterministic behavior during synchronization and protects audit integrity.

Source-of-Truth Resolution Flow

Data domain identified
→ Owning site assigned
→ Write operations restricted
→ Read-only propagation enabled

Ownership Assignment Examples

Data Entity	Owning Site
Item master	Central master site
Customer master	Regional sales site
Supplier master	Procurement hub site

Governance Rule

• Ownership is defined once and enforced forever
• Ownership must be documented outside the system
• No emergency overrides in production

7. One-Way vs Bi-Directional Synchronization Architecture

Synchronization architecture defines how data flows between sites. ERPNext multi-site implementations should strongly prefer one-way synchronization over bi-directional models.

Bi-directional synchronization introduces conflict resolution, ordering problems, and audit ambiguity. ERPNext provides no native tools to resolve these safely.

One-way flows preserve determinism and simplify failure recovery.

Synchronization Direction Flow

One-way sync
→ Source site publishes
→ Target site consumes

Bi-directional sync
→ Multiple publishers
→ Conflict potential

Architecture Comparison

Model	Risk Level	Recommended
One-way	Low	Yes
Bi-directional	High	No
Hub-and-spoke	Medium	Conditional

Design Principle

• Prefer unidirectional data flow
• Avoid mutual writes at all cost
• Complex sync is harder to audit than manual correction

8. Incremental Synchronization vs Full Data Synchronization

ERPNext multi-site environments must choose between incremental and full synchronization strategies. The choice affects performance, data consistency, and operational risk.

Incremental sync tracks changes since the last successful run, while full sync reprocesses the entire dataset.

Incremental synchronization is the default choice for production systems.

Synchronization Strategy Flow

Change detected
→ Incremental sync triggered
→ Target updated

OR

Full dataset selected
→ Bulk transfer executed
→ Target reconciled

Strategy Comparison

Aspect	Incremental	Full
Performance	High	Low
Risk	Low	High
Use case	Daily operations	Initial setup / recovery

Operational Guidance

• Use full sync only during onboarding
• Track last sync timestamp reliably
• Never mix strategies mid-cycle

9. Master Data Synchronization – Internal Execution Logic

Master data synchronization is the safest and most common multi-site synchronization use case. ERPNext masters are relatively stable and have limited transactional side effects.

Even so, master synchronization must respect naming conventions, default values, and validation rules on the target site.

Master sync should never bypass validations.

Master Sync Execution Flow

Master updated on source
→ Change captured
→ Payload generated
→ Target validation executed
→ Record created or updated

Common Master Sync Targets

Master	Sync Suitability
Item	High
Customer	High
Supplier	High
Price List	Medium

Design Constraints

• Respect naming series on target site
• Do not override local defaults blindly
• Log every master sync action

10. Transaction Synchronization Constraints and Risk Boundaries

Transactional data synchronization is inherently dangerous in ERPNext multi-site environments. Transactions carry financial, inventory, and audit implications that cannot be safely replayed.

ERPNext does not support cross-site transactional integrity. As a result, transactions should be referenced, not duplicated.

Most production systems avoid transaction synchronization entirely.

Transaction Handling Flow

Transaction created
→ Reference identifier generated
→ Metadata shared (optional)
→ No ledger or stock copied

Transaction Sync Risk Matrix

Transaction	Recommended Action
Sales Invoice	Do not sync
Purchase Invoice	Do not sync
Stock Entry	Never sync
Sales Order	Reference only

Hard Rule

• Never sync GL entries across sites
• Never sync stock ledgers
• Use reporting APIs instead of replication

11. Document Identity, Naming Conflicts, and Record Mapping

In multi-site synchronization, document identity is the most overlooked and most dangerous problem. ERPNext document names are not globally unique and are often generated using local naming series.

When the same document type exists on multiple sites, name collisions become inevitable unless an explicit identity strategy is enforced.

Document identity must therefore be decoupled from document naming.

Identity Resolution Flow

Document created
→ Local name assigned
→ Global identifier generated
→ Mapping stored externally

Identity Components

Component	Purpose
Local name	ERPNext internal reference
External ID	Cross-site identity
Source site code	Origin identification

Design Rule

• Never rely on document name across sites
• Always store an external identifier
• Identity mapping must be immutable

12. UUID, Hash, and External ID Strategies

A globally unique identifier is mandatory for safe synchronization. ERPNext does not generate such identifiers by default, so they must be introduced explicitly.

UUIDs provide randomness, while hashes provide content-based identity. Each approach has trade-offs in traceability and performance.

External IDs should be generated at creation time and never modified.

Identifier Generation Flow

Document created
→ UUID generated
→ External ID stored
→ Used for all sync operations

Identifier Strategy Comparison

Strategy	Pros	Cons
UUID v4	Globally unique	Not human-readable
Content hash	Change detection	Breaks on updates
Composite key	Readable	Collision risk

Governance Principle

• Generate identifiers once
• Never regenerate identifiers
• Never expose ERPNext names externally

13. API-Based Synchronization – Internal Execution Flow

API-based synchronization is the most common and controllable approach for ERPNext multi-site data exchange. Each site exposes a controlled API endpoint for inbound synchronization.

The receiving site must treat all inbound API calls as untrusted input, even if they originate from internal systems.

Validation and permission checks must never be bypassed.

API Sync Execution Flow

Source site detects change
→ API payload generated
→ Secure API call executed
→ Target validation applied
→ Commit or reject

API Responsibilities

Layer	Responsibility
Source	Payload accuracy
Transport	Authentication & encryption
Target	Validation & persistence

Security Rule

• Never expose standard CRUD endpoints
• Use custom sync-specific APIs
• Log every inbound request

14. Webhook-Driven Synchronization and Event Architecture

Webhooks enable event-driven synchronization, where changes are propagated immediately after they occur. This reduces latency but increases coupling between sites.

ERPNext webhooks trigger on document events such as creation, update, or submission. These events must be filtered carefully.

Not all events are suitable for propagation.

Webhook Event Flow

Document event triggered
→ Webhook payload generated
→ Remote endpoint called
→ Event queued or processed

Webhook Suitability

Event Type	Recommended
Master update	Yes
Transaction submit	No
Status change	Conditional

Design Constraint

• Webhooks must be idempotent
• Failures must not block transactions
• Queue processing is mandatory

15. Scheduler-Based Batch Synchronization

Scheduler-based synchronization is used for predictable, low-frequency data exchange. It trades immediacy for reliability and control.

Batch jobs reduce load spikes and allow synchronization to be paused, resumed, or rerun safely.

This approach is preferred for large master datasets.

Batch Sync Execution Flow

Scheduler triggered
→ Changes queried
→ Batch payload prepared
→ Target sync executed
→ Status recorded

Batch Sync Characteristics

Aspect	Behavior
Frequency	Scheduled
Error handling	Retryable
Auditability	High

Operational Rule

• Never mix batch and real-time logic
• Track sync state persistently
• Design jobs to be restart-safe

16. Conflict Detection and Resolution Logic

Conflict detection is required whenever synchronized data can be modified independently on more than one site. Even with strict ownership rules, misconfiguration or manual intervention can introduce conflicts.

ERPNext does not provide native conflict resolution mechanisms across sites. Any resolution strategy must therefore be explicitly implemented outside core transaction flows.

Conflict resolution must never alter historical or audited data.

Conflict Detection Flow

Incoming sync payload
→ External ID matched
→ Last modified timestamp compared
→ Ownership validated
→ Conflict flagged or accepted

Common Conflict Types

Conflict Type	Description
Concurrent updates	Same record modified on multiple sites
Ownership violation	Non-owning site attempts write
Schema mismatch	Field structure inconsistency

Resolution Rule

• Reject conflicting writes by default
• Never auto-merge transactional data
• Resolve conflicts manually with audit oversight

17. Validation Layers Before Data Persistence

All synchronized data must pass through the same validation layers as locally created documents. Synchronization is not a bypass mechanism.

ERPNext validation includes schema validation, business rule enforcement, and permission checks. Skipping any layer introduces data corruption risk.

Validation failures must be treated as sync failures, not system errors.

Validation Execution Flow

Payload received
→ Schema validation
→ Business rule validation
→ Permission validation
→ Persist or reject

Validation Categories

Layer	Purpose
Schema	Field and datatype integrity
Business rules	ERPNext domain logic
Permissions	Access control enforcement

Design Principle

• Never disable validation for sync
• Surface validation errors clearly
• Fix data at source, not target

18. Failure Handling, Retries, and Recovery Strategy

Synchronization failures are expected in distributed systems. Network issues, validation errors, or remote downtime must not compromise data integrity.

ERPNext multi-site sync must therefore be designed with retry and recovery as first-class concerns.

Failures must be isolated, logged, and recoverable.

Failure Handling Flow

Sync attempt fails
→ Error captured
→ Retry scheduled
→ Max retries evaluated
→ Manual intervention triggered if needed

Failure Categories

Failure Type	Action
Network error	Retry automatically
Validation error	Fix source data
Authorization error	Stop and investigate

Operational Rule

• Retries must be idempotent
• Never retry indefinitely
• Expose failures to operators

19. Idempotency and Duplicate Prevention

Idempotency ensures that repeated sync attempts do not create duplicate records or corrupt data. This is critical in retry-based architectures.

ERPNext does not enforce idempotency at the application level. It must be designed explicitly into synchronization logic.

Every sync operation must be safely repeatable.

Idempotency Control Flow

Payload received
→ External ID checked
→ Existing record matched
→ Update or ignore

Duplicate Prevention Mechanisms

Mechanism	Purpose
External ID	Unique record mapping
Sync log table	Execution tracking
Hash comparison	Change detection

Hard Rule

• Never create records blindly
• All writes must be idempotent
• Duplicates indicate design failure

20. Security, Authentication, and Authorization

Multi-site synchronization expands the attack surface of ERPNext deployments. Each sync endpoint must be secured as rigorously as public-facing APIs.

Authentication establishes who is calling, while authorization determines what the caller may do. Both are mandatory.

Security failures in sync logic have system-wide consequences.

Security Enforcement Flow

Request received
→ Token validated
→ Source site verified
→ Permission scope checked
→ Processing allowed or denied

Security Controls

Control	Purpose
API tokens	Caller authentication
IP restrictions	Network-level trust
Scoped permissions	Least privilege

Security Principle

• Never reuse user credentials for sync
• Rotate tokens periodically
• Audit all sync access

21. Performance and Load Management in Multi-Site Synchronization

Synchronization introduces additional load on both source and target ERPNext sites. If not controlled, sync processes can interfere with normal transactional workloads.

Performance considerations must be part of synchronization architecture, not an afterthought. Poorly designed sync logic can degrade user experience and destabilize production systems.

Load must be predictable, throttled, and observable.

Performance Management Flow

Sync triggered
→ Load evaluated
→ Throttling applied
→ Execution scheduled
→ Metrics collected

Performance Control Techniques

Technique	Purpose
Rate limiting	Prevent API overload
Batch sizing	Control memory usage
Off-peak scheduling	Avoid peak hours

Operational Rule

• Never sync during peak transaction hours
• Monitor sync latency continuously
• Scale workers independently from users

22. Data Volume Management and Pagination Strategy

As ERPNext databases grow, synchronization must handle large volumes of data safely. Attempting to sync entire datasets in a single operation is neither reliable nor scalable.

Pagination and windowing are mandatory for large data sets. They allow progress tracking and controlled recovery.

Volume must always be bounded.

Pagination Execution Flow

Dataset identified
→ Page size defined
→ Windowed queries executed
→ Progress checkpoint recorded

Pagination Controls

Control	Purpose
Page size	Memory and time control
Offset / cursor	Deterministic ordering
Checkpoint	Resume capability

Design Guidance

• Prefer cursor-based pagination
• Never rely on implicit ordering
• Persist pagination state externally

23. Synchronization Logging and Audit Trail

Synchronization without logging is operationally blind. Every sync attempt, success or failure, must be recorded with sufficient detail for audit and troubleshooting.

Sync logs serve as the only reliable evidence of cross-site data movement. They must be immutable and queryable.

Logs are not optional.

Audit Logging Flow

Sync initiated
→ Metadata captured
→ Execution performed
→ Outcome recorded

Mandatory Log Attributes

Attribute	Purpose
External ID	Record traceability
Source and target site	Ownership tracking
Timestamp	Chronological audit
Status	Success or failure

Audit Rule

• Never delete sync logs
• Protect logs from modification
• Expose logs to audit teams

24. Rollback, Recovery, and Data Correction Design

Rollback in distributed systems is fundamentally limited. Once data is persisted on a target site, it cannot be undone automatically without introducing further risk.

Recovery strategies must therefore focus on correction, not reversal. This requires traceability and controlled compensating actions.

Rollback expectations must be realistic.

Recovery Design Flow

Error identified
→ Impact assessed
→ Corrective action designed
→ Manual or scripted correction applied

Recovery Mechanisms

Mechanism	Use Case
Compensating update	Incorrect master data
Manual correction	Audit-sensitive changes
Reference invalidation	Erroneous linkage

Design Principle

• Never assume automatic rollback
• Design for correction, not deletion
• Always preserve audit trail

25. Version Compatibility and Schema Evolution

ERPNext sites participating in synchronization may not always run the same application version. Differences in schema, validation rules, or business logic can break synchronization silently.

Version compatibility must be explicitly managed. Assuming homogeneous versions is unsafe in long-running systems.

Schema evolution must be planned.

Compatibility Management Flow

Source version detected
→ Target version evaluated
→ Payload adapted if required
→ Sync executed or blocked

Compatibility Risks

Risk	Impact
Missing fields	Data loss
Changed validations	Sync failure
Deprecated logic	Inconsistent behavior

Governance Rule

• Version-sync critical sites together
• Block sync on incompatible schemas
• Document schema changes explicitly

26. Custom App Strategy for Multi-Site Synchronization

Multi-site synchronization in ERPNext should never be implemented as ad-hoc scripts or isolated automation rules. It must be encapsulated within a dedicated custom application.

A custom app provides version control, deployment consistency, testability, and governance. Synchronization logic is core infrastructure, not a one-off integration.

Treat sync code as a long-lived system component.

Custom App Architecture Flow

Custom app created
→ Sync modules defined
→ APIs, schedulers, and logs centralized
→ Deployed consistently across sites

Recommended App Components

Component	Responsibility
Sync API	Inbound data handling
Scheduler jobs	Batch execution
Mapping tables	Identity resolution
Sync logs	Audit and traceability

Design Principle

• Never embed sync logic in core ERPNext
• Version-control all sync behavior
• Deploy and upgrade sync apps deliberately

27. Production Deployment and Go-Live Checklist

Synchronization failures in production are costly and disruptive. A formal deployment checklist is mandatory before enabling multi-site sync.

Go-live should be treated as a controlled release, not an experimental rollout.

Every assumption must be validated.

Go-Live Validation Flow

Pre-production tested
→ Security verified
→ Ownership rules validated
→ Sync enabled gradually

Production Readiness Checklist

Area	Status Required
External ID generation	Verified
Authentication tokens	Secured
Retry and logging	Enabled
Rollback strategy	Documented

Operational Rule

• Enable sync in stages
• Monitor logs continuously during go-live
• Freeze schema changes during rollout

28. Common Multi-Site Synchronization Failures

Most synchronization failures are architectural, not technical. They stem from unclear ownership, over-ambitious scope, or governance gaps.

These failures often surface late, during audits or reconciliation, when correction is expensive.

Prevention is cheaper than recovery.

Failure Pattern Flow

Poor design decisions
→ Uncontrolled sync
→ Data inconsistencies
→ Audit and trust issues

Frequent Failure Scenarios

Failure	Impact
Bi-directional writes	Unresolvable conflicts
Transaction replication	Ledger corruption
Missing audit logs	Compliance failure

Prevention Strategy

• Enforce ownership rules strictly
• Limit sync scope aggressively
• Design for audit first, convenience second

29. Governance, Ownership, and Operational Responsibility

Synchronization is not a technical feature; it is a governance model. Clear ownership and accountability are required to operate it safely.

Every synchronized domain must have a business owner, a technical owner, and an operational escalation path.

Without governance, sync logic becomes unmanageable.

Governance Responsibility Flow

Data domain defined
→ Owner assigned
→ Rules documented
→ Enforcement audited

Ownership Model

Role	Responsibility
Business owner	Data correctness
Technical owner	Sync reliability
Operations	Monitoring and recovery

Governance Rule

• No sync without a named owner
• Changes require cross-team approval
• Audit ownership periodically

30. Multi-Site Synchronization as a Long-Term Architecture

Multi-site synchronization in ERPNext is not a shortcut and not a convenience feature. It is a long-term architectural commitment that affects compliance, scalability, and trust.

When designed correctly, it enables distributed growth while preserving control. When designed poorly, it becomes a permanent operational risk.

Architecture choices made early are difficult to reverse later.

Architecture Lifecycle

Business structure defined
→ Ownership model established
→ Sync architecture implemented
→ Long-term stability maintained

Strategic Value

Aspect	Outcome
Isolation	Legal and audit safety
Control	Predictable data flow
Scalability	Enterprise readiness

Final Principle

• Synchronize intentionally, not broadly
• Protect boundaries rigorously
• Treat synchronization as core architecture