Dolibarr ERP/CRM and WordPress / WooCommerce synchronisation

DoliCommerce Bridge: connect Dolibarr ERP/CRM and WooCommerce, reliably

Stop re-typing orders, stock levels and prices by hand. DoliCommerce Bridge is the Dolibarr module that keeps your WooCommerce shops and your Dolibarr back-office in sync: customers, products, variations, stock, prices, orders, invoices, payments, refunds and shipments, all through a secure, auditable queue that lives entirely inside Dolibarr.

Published by NextGestion, version 1.0, licensed GPL v3 or later. No WordPress plugin to install. No core file of Dolibarr, WordPress or WooCommerce modified.

Overview

Running an online shop on WooCommerce while managing your business in Dolibarr usually means double data entry or a fragile script nobody dares to touch. DoliCommerce Bridge replaces both with a structured synchronisation engine.

The module connects one Dolibarr entity to any number of WooCommerce shops. Each connection has its own credentials, catalogue scope, warehouses, currency, language, price level, mappings, rules, queue, logs, webhooks and schedules. It communicates with WooCommerce through the official REST API v3, with WordPress through its REST API, and receives signed WooCommerce webhooks.

Every change (a Dolibarr trigger, a webhook, a scheduled delta or a click in the interface) becomes a job in a persistent queue, processed by a worker run by Dolibarr's scheduled jobs. No remote call is made while a user saves a record in Dolibarr or while WooCommerce delivers a webhook, so neither system slows the other down.

Key benefits

• Stop re-typing orders. Paid WooCommerce orders arrive in Dolibarr with their lines, taxes, shipping, invoice and payment, according to your rules.
• Sell only what you have. Stock movements in Dolibarr are pushed to the shop within minutes, with optional safety stock.
• Keep your accounting clean. Idempotency keys prevent duplicates, amount verification prevents silent discrepancies, refunds become credit notes.
• Decide who is the master. Directions and sources of truth are set per data family and per field, not imposed by the tool.
• Survive real-world incidents. Shop down, expired credentials, lost webhook, stopped CRON: jobs wait, retry, or land in a dead letter queue you can fix and replay.
• See everything. Dashboard, health metrics, correlated logs, diagnostic checks and per-site reports.
• Scale to several shops. One Dolibarr, many WooCommerce sites, each with its own configuration.
• Go live safely. The wizard ends with a dry run showing exactly what would be created, updated or put into conflict.

Detailed features

Customers and contacts

• WooCommerce customers synchronised with Dolibarr third parties, including billing and shipping contacts.
• Deduplication by remote id, e-mail, reference and VAT number; ambiguous matches are never selected automatically.
• Guest orders: one third party per e-mail (hashed key) or a single generic third party.
• B2B detection when the company field is filled; WordPress roles mapped to third-party type, group, price level and category.

Catalogue and variations

• Simple products, services (as virtual products), variable products and variations, using the Dolibarr Variants module or a "separate products" mode.
• Category tree, product tags (as Dolibarr categories under "WooCommerce Tags"), global attributes and terms.
• Main, gallery and variation images, with SHA-256 hashing to avoid re-uploads and hardened secure download on import.
• Weights and dimensions with automatic unit conversion; EAN/GTIN barcodes (native field from WooCommerce 9.2).
• Grouped, external, downloadable, upsell and cross-sell data preserved in mapping metadata, so nothing is lost.
• Configurable handling of deleted products, never an automatic deletion in Dolibarr.

Multi-warehouse stock and prices

• WooCommerce holds one stock per product, so you choose: single warehouse, sum of warehouses, or custom mapping with coefficients and safety stock.
• Stock pulled from WooCommerce creates a genuine Dolibarr stock movement.
• Regular prices with excl./incl. tax base following the WooCommerce tax setting.
• Sale prices through a dedicated extrafield or price level; role-based prices through a detected B2B plugin adapter.

Orders, invoices, payments and refunds

• Order import by webhook plus a 5-minute delta, filtered by status and minimum date.
• Lines with products, variations, SKU, quantities, unit prices, taxes, discounts, shipping, fees and coupons.
• Configurable order status mapping in both directions.
• Automatic invoice creation on the trigger you choose: created, payment, processing, completed, shipped or never.
• Payments derived from the order: date paid, transaction id, gateway mapped to a payment type and bank account.
• Full or partial refunds (quantities, shipping, fees, taxes, reason) turned into credit notes, with optional restocking.
• Currency and original amounts preserved, Dolibarr multicurrency rate applied.
• Totals compared with a 0.02 tolerance by default: any mismatch opens a financial conflict and an alert instead of silent validation. Real gateway refunds are never triggered automatically.

Shipments and tracking

• Validating or closing a Dolibarr shipment completes the WooCommerce order once everything is shipped.
• Tracking numbers pushed to Shipment Tracking, Advanced Shipment Tracking, or a generic meta field plus customer note.
• Shipping methods mapped per zone instance to Dolibarr shipping modes.

Taxes and coupons

• WooCommerce tax rates and tax classes imported as VAT mapping suggestions.
• Coupon definitions kept in a local mirror table, since Dolibarr has no coupon object; coupon lines are imported with orders.

Mappings and sources of truth

• Direction per family: Dolibarr master, WooCommerce master, bidirectional, manual only or disabled.
• Source of truth per field: Dolibarr, WooCommerce, most recent, or always manual.
• Field-level three-way merge against the last synchronised snapshot.
• Editable mappings for statuses, taxes, payments, shipping, warehouses, roles and custom fields (Dolibarr extrafields to WooCommerce metadata, with type conversion).
• Rule engine: IF conditions THEN actions.

Conflict Center

When both sides change the same field and no rule decides, the difference lands in the Conflict Center. An authorised user keeps the Dolibarr value, keeps the WooCommerce value, or ignores the difference. Financial conflicts are handled there too.

Queue, retries, webhooks and CRON

• Persistent queue with priorities, coalescing, dead letter queue, payload editing and requeue.
• Exponential backoff with jitter, shared rate limiter, per-connection circuit breaker and stale job recovery.
• Five anti-loop barriers and exactly-once financial operations protected by idempotency keys; webhook deliveries deduplicated by Delivery-ID.
• Signed webhook receiver with automatic registration and repair.
• Scheduled deltas (5 minutes for orders, 10 for stock by default) and a nightly reconciliation of missing objects, broken mappings and stock, price or amount gaps.

Dashboard, logs, diagnostic and reporting

• Sync Center dashboard with health metrics and notifications.
• Detailed logs with correlation ids and personal data masking.
• Diagnostic page with fifteen check groups; connection test detecting WordPress/WooCommerce versions, HTTPS, permalinks, currency, taxes, HPOS, statuses, gateways, shipping methods and plugins.
• Multi-site reporting with exports, based on a local index of imported orders.
• "WordPress / WooCommerce" tab on Dolibarr product, third-party, order and invoice cards, with a "Synchronise now" button; bulk synchronisation.

First-sync wizard and dry run

A 14-step wizard guides you from the connection test to go-live: general parameters, directions and sources of truth, status, tax, payment and shipping mappings, warehouses, filters and rules, and matching of existing data. The dry-run simulation writes nothing (not in Dolibarr, not in WooCommerce, not in mapping tables) and reports create, update, unchanged, conflict or skip for each object.

Multi-site

• Unlimited WooCommerce shops per Dolibarr entity, multi-company aware.
• Connection status Active, Paused or Disabled: pausing postpones jobs without losing them.

Security and GDPR

• Credentials encrypted with AES-256-GCM, masked on screen and never logged.
• HMAC webhook signature verification, CSRF protection and Dolibarr rights checks.
• Authentication by HTTP Basic over HTTPS, query-string keys over HTTPS, or OAuth 1.0a (plain HTTP, not recommended).
• Personal data masked in logs, logs purged after 90 days and finished jobs after 14 days, guest customers grouped by hashed e-mail.

Synchronisation summary

All directions are configurable per family and per connection.

Requirements

• Dolibarr 17.0 or later.
• PHP 7.4 to 8.4 with curl, json, openssl and mbstring extensions.
• MySQL or MariaDB.
• WordPress with WooCommerce and its REST API v3; HTTPS strongly recommended.
• A WooCommerce Read/Write API key owned by a shop manager or administrator; a WordPress application password (WordPress 5.6 or later) for media upload.
• Dolibarr modules Third parties and Products, plus Stock, Orders, Invoices, Shipments, Variants, Multicurrency, Categories or Bank as needed, and Scheduled jobs (required for the worker).
• A system crontab running Dolibarr's scheduled jobs every minute.

Installation

1. Upload the module archive through Home, Setup, Modules, Deploy external module (or unzip it into htdocs/custom/).
2. Enable DoliCommerce Bridge, the Scheduled jobs module and the Dolibarr modules you need.
3. Grant module rights to the relevant users and groups.
4. Configure the system crontab calling Dolibarr's scripts/cron/cron_run_jobs.php every minute.
5. In WooCommerce, create a Read/Write REST API key; in WordPress, create an application password if you need image upload.
6. Open the Commerce Sync menu, launch the wizard, enter the shop URL and keys, and run the connection test.
7. Configure directions, mappings, warehouses and rules, then run the dry-run simulation and review the report.
8. Go live: the wizard queues the initial import/export, registers webhooks and activates the connection. Check the Diagnostic page and the Dashboard.

Compatibility: an honest statement

Version 1.0 is covered by an automated test suite run on PHP 8.3 with SQLite, in-memory doubles of Dolibarr and WooCommerce and a mocked HTTP transport. No runtime test has been performed on a real Dolibarr, WordPress or WooCommerce installation.

• Dolibarr 17 to 22: designed for these versions, not tested on a real instance. Dolibarr below 17: not compatible.
• PHP 7.4 to 8.4: supported (automated suite executed on PHP 8.3 only).
• WooCommerce REST API v3 (8.x, 9.x, with or without HPOS): expected to be compatible through standard endpoints, not verified. Legacy API v1/v2: not compatible.
• Tracking, SEO, multilingual, PDF invoice and B2B pricing plugins: detection-based adapters, not tested.
• PrestaShop, Shopify, Magento: not supported in version 1.0.

We strongly recommend a full acceptance test on a staging copy of your Dolibarr and WooCommerce before switching your production shop.

Interface languages

French, English, Spanish, German and Italian.

Package contents

• The DoliCommerce Bridge 1.0 module archive, ready to deploy in Dolibarr.
• User and technical documentation (architecture, database schema, API capabilities, compatibility, synchronisation matrix).
• A training manual (PDF, French).

Frequently asked questions

Do I need to install a plugin on WordPress?

No. The module uses the standard WooCommerce REST API v3, the WordPress REST API and WooCommerce webhooks. You only create an API key and, for images, an application password.

Is synchronisation real time?

Near real time. Webhooks and Dolibarr triggers enqueue jobs immediately and the worker runs every minute. Scheduled deltas catch anything a webhook missed.

Who is the master: Dolibarr or WooCommerce?

You decide per family and per field. By default Dolibarr masters catalogue, stock and prices, while WooCommerce masters customers and orders.

Can a replayed webhook create a duplicate invoice or payment?

No. Orders, invoices, payments, refunds, credit notes and shipments use idempotency keys, and webhook deliveries are deduplicated by their Delivery-ID.

Will the module refund my customers automatically?

No. A WooCommerce refund becomes a Dolibarr credit note. A real gateway refund is disabled by default and requires explicit configuration.

What happens if my shop is down or my API key expires?

Network and server errors are retried with exponential backoff and the circuit breaker pauses calls to that shop. Invalid credentials send jobs to the dead letter queue with a critical alert, avoiding retry storms.

Can I connect several shops to one Dolibarr?

Yes. Each connection has its own credentials, scope, warehouses, currency, language, price level, mappings, rules, queue, logs and webhooks.

Has the module been tested on real shops?

Not yet. Version 1.0 is validated by an automated test suite only. Please validate it on a staging copy before production use.

Support

DoliCommerce Bridge is developed and supported by NextGestion, specialist in Dolibarr ERP/CRM solutions. For questions, assistance or custom developments, visit https://www.nextgestion.com.

Demo of the DoliCommerce Bridge (WordPress / WooCommerce) module
Login : demo
Password : demo