NextShop Bridge – Shopify ⇄ Dolibarr synchronization and migration

Connect your Shopify stores to Dolibarr, keep your e-commerce operations in sync every day and migrate your history while staying in control of your data. NextShop Bridge is a professional Dolibarr module published by NEXT GESTION that combines a multi-store Shopify connector, a bidirectional synchronization engine, a file import center, a migration wizard, a reconciliation center and an operations dashboard.

This is not just another order connector: it is a complete commerce platform for merchants, integrators and companies that want Dolibarr to become their central ERP/CRM. The module relies exclusively on the Shopify GraphQL Admin API (reference version 2026-07), on Shopify webhooks and on Dolibarr's official extension mechanisms: triggers, hooks, extra fields, scheduled jobs, REST API and permissions. No Dolibarr core file is modified.

Why choose NextShop Bridge?

• Multiple stores: several Shopify stores on a single Dolibarr instance, each with its own currency, warehouses, mappings, webhooks and logs.
• Per-object synchronization: Shopify → Dolibarr, Dolibarr → Shopify, bidirectional or disabled, with a source of truth you set field by field.
• No duplicates: every order, payment and refund is keyed by its Shopify ID and its connection; replaying a webhook or re-importing a file never creates a second record.
• Financial integrity: subtotal, discounts, shipping, taxes, total, paid and refunded amounts are compared; any difference above your tolerance becomes a visible conflict with its probable cause.
• Technical truth principle: every feature is announced with its actual support level. A limitation is never presented as a feature.
• Dry run before any real import, and a PDF migration report at the end.

Shopify connection and authentication

• Three authentication methods: installed-app access token, OAuth authorization code grant (state and HMAC verified, tokens refreshed) and client credentials for stores in the same Shopify organization.
• Connection test: store, status, API version actually served, currency, time zone, plan, locations, volumes, active webhooks and granted scopes.
• Shopify permissions screen: for each area, the module states whether access is granted and which feature is affected when a scope is missing.
• API versions: 2026-07 by default, 2026-04 as the technical floor, 2026-10 from its release; the version header returned by Shopify is checked on every response. Tokens and secrets are encrypted in the database (AES-256-GCM), masked on screen and redacted from logs.

Bidirectional synchronization, object by object

For each object, the administrator picks the direction and the source of truth: Shopify master, Dolibarr master, last modification wins, or manual resolution. The defaults match the most common setup.

Sync loops are prevented by correlation identifiers, the origin of each write and a hash of the last synchronization: a change echoed back by Shopify right after a Dolibarr write is ignored. After the initial migration, delta synchronization only processes changes. No deletion is ever propagated automatically.

B2C and B2B customers

• Shopify customers become Dolibarr third parties and/or contacts. For B2C, choose one third party per customer or one generic third party with one contact per customer; guest checkouts follow the same rules.
• Shopify ID, name, email, phone, company, language, status, tags, notes and dates; main, billing and shipping addresses, never deleted implicitly on the Shopify side. Marketing consent is stored only when the option is enabled; duplicates are detected by Shopify ID, then by natural keys.
• B2B companies: imported as third parties, contacts and addresses when the store has the B2B feature under its Shopify plan and the matching scope.

Products, variants, collections and images

• ID, handle, title, description, vendor, product type, status, tags, collections, images, SEO, metafields and dates.
• Variants (Red/S, Red/M, Blue/S…): when the Dolibarr Variants module is enabled, the parent product and its attribute combinations are created; otherwise each variant becomes a sellable product whose reference is the SKU. SKU, barcode, options, price, compare-at price, weight and stock are handled at variant level.
• Collections imported as categories; tags, vendor and product type kept in dedicated extra fields and, optionally, turned into categories; unit cost mapped to the Dolibarr cost price.
• Images imported as product documents (duplicate detection by ID, URL and SHA-256 hash, downloads restricted to Shopify hosts). A product becomes a Dolibarr service only when an explicit rule says so.

Multi-warehouse inventory and Shopify locations

• Location mapping: each Shopify location is linked to a Dolibarr warehouse, in one of three modes (one location = one warehouse, several locations summed, or a per-location rule).
• "Available" quantities imported through correction movements; committed and incoming states are read for information.
• Writes to Shopify use a check on the previous quantity plus an idempotency key: a mismatch becomes a stock conflict instead of being overwritten, and both systems are compared continuously.

Orders, invoices, payments and refunds

• Orders: number, date, customer or guest, contact details, billing and shipping addresses, currency, product and variant lines (SKU, quantity, unit price), line, order and shipping discounts with their origin, taxes, shipping charges, notes, tags and statuses.
• Multi-currency: original currency and amounts always kept, exchange rate used when available.
• Invoices: the flow is Shopify order → Dolibarr order → Dolibarr invoice, with a configurable trigger (order creation, payment, fulfillment or manual).
• Payments: only successful sale and capture transactions create a Dolibarr payment; authorizations and voids are traced without accounting entries. Gateways (Shopify Payments, PayPal, Stripe, card, bank transfer, cash on delivery…) are mapped to Dolibarr payment methods and bank accounts through an open mapping where new gateways appear automatically.
• Refunds: lines, quantities, amounts, taxes, refunded shipping, reason and transactions; a Dolibarr credit note is created when the rule requires it and the match is reliable, otherwise a conflict is raised.
• Returns: the return, its lines, status, related refund and restocking are tracked. Return, refund and cancellation are strictly distinguished: a return without a refund never creates a credit note.
• Fulfillments and tracking: Shopify fulfillments imported as Dolibarr shipments, and a fulfillment created in Shopify when a shipment is validated (quantities, carrier, tracking number and URL), with carrier mapping.
• Taxes, discounts, metafields: per-line VAT with title / rate / country mapping, discounts with their origin, typed metafields converted into extra fields.

Real time, queue and resilience

• Signed webhooks: HMAC-SHA256 signature verified on the raw body, non-authentic events rejected, replay protection and de-duplication. Events covered: customers, products, orders, transactions, refunds, returns, fulfillments, inventory, locations, bulk operations and app uninstall.
• Prioritized queue (payments at critical priority), automatic retries (1 min, 5 min, 15 min, 1 h) and a replayable dead-letter queue.
• Rate limiting driven by GraphQL query cost and a circuit breaker when Shopify is unavailable: calls are suspended, the queue is preserved, nothing is lost.
• Bulk operations (JSONL processed as a stream) with tracking, download, parsing and resume.

CSV / Excel / ZIP Import Center

• Drag and drop CSV, XLS, XLSX and ZIP files exported from Shopify or edited in a spreadsheet.
• File inspector: extension, MIME type, encoding, separator, rows, columns, headers, dates, currencies, decimals, empty values, duplicates and errors.
• Type detection (customers, products, variants, inventory, orders, transactions) with a confidence score and manual override. Current and legacy Shopify formats are recognized: a multi-row product stays one product and the lines of an order are grouped.
• Visual mapping: automatic, manual, ignored column, constant value or transformation, with reusable templates recognized the next time the same file is imported.
• Transformation engine: trim, replace, regular expression, split, concatenate, date and decimal conversion, dictionary, HTML cleanup.
• Dry run: analysis with no writes at all (to create, to update, already present, conflicts, errors), then batch import.
• Idempotence: batch reference plus a fingerprint of the file and of every row; re-importing the same file creates no duplicates.
• Security: maximum size, zip bombs blocked, forbidden types, CSV formula injection neutralized, Excel formulas never executed.

Migration, reconciliation and switchover

• 16-step migration wizard: store identification, source choice (API or files), analysis, Dolibarr setup, warehouse, tax, customer and product mapping, import of the catalog, customers, orders and transactions, then checks and validation.
• History migration: all accessible data, the last 12 or 24 months, or a custom period, using bulk operations.
• Reconciliation center: customers, products, inventory, orders, amounts, payments, refunds and fulfillments, with the detail of every difference. Scheduled full reconciliation covers missing objects, broken mappings, orphan payments and unprocessed refunds.
• Conflict center: object, field, Shopify and Dolibarr values, dates and source, with the actions "keep Shopify", "keep Dolibarr", "ignore" or "create a rule".
• "Ready to leave Shopify?" page: completeness rate per area and remaining anomalies. It measures technical completeness and never claims that Shopify can be closed: that decision stays yours.
• Switchover checklist and PDF migration report: store, period, volumes, errors, conflicts and differences.

Dashboard, reporting and operations

• Shopify Commerce Sync Center: stores, customers, products, orders, synchronized revenue, payments, refunds, fulfillments, stock mismatches, queue, errors, conflicts and success rate, with built-in charts and an activity feed.
• Reports: sales, orders, customers, products, inventory, payments, refunds, fulfillments, synchronization, errors and migration, exportable to CSV, Excel (XLSX) and PDF.
• Detailed logs (date, store, object, identifiers, direction, action, status, duration, message) and a diagnostic center; demo data can be generated and removed without touching real records.

Security and GDPR

• CSRF protection, systematic output escaping (XSS), protected SQL queries, input validation and SSRF protection: only allowed Shopify hosts are contacted.
• Uploaded files checked (types, sizes, archives, paths) and stored outside the web root.
• GDPR: Shopify customer-data and redaction requests handled, with export, controlled deletion and an audit trail.
• 17 distinct Dolibarr permissions: read access, setup, stores, per-area synchronization, import, migration, conflicts, queue, logs and administration.

Performance

GraphQL, bulk operations, cursor pagination, batch processing, streaming file reading, SQL indexes and delta synchronization keep large volumes manageable. Measured on test files: parsing 100,000 rows (20,000 products) in about 1.6 s using 4 MB of memory, inspecting and staging the same volume in under 4 s using less than 32 MB (Dolibarr 24.0.1 and 18.0.10). Real-world performance depends on your server and on Shopify API limits.

Limitations and transparency

NEXT GESTION applies a technical truth principle. Here is what NextShop Bridge does not do, or does only partially.

• Testing was done with simulated data (fixtures and a mock Shopify server): no live Shopify store has been tested to date. A validation run on your own store remains essential.
• Not supported: pushing Dolibarr images to Shopify; creating invoices, payments or refunds on the Shopify side; Shopify Markets; videos and 3D models; gift cards and subscriptions.
• Partially supported: returns (tracking only); discount codes (browsable archive, as Dolibarr has no equivalent object); multi-jurisdiction taxes (closest rate with a difference check); automatic collections (imported read-only); metaobjects (JSON archive).
• Shopify access required: beyond 60 days of order history the read_all_orders scope must be requested from Shopify; protected customer data requires level 2 access; B2B companies depend on your Shopify plan.
• Writes to Shopify: only draft orders can be created, and that option is disabled by default; order edits are not pushed back; products with more than 3 options or 2,048 variants are not pushed.
• Deletions are never automatic: each one is confirmed individually in the conflict center, and orders are never deleted. File imports run while the run page stays open; JSON and JSONL cannot be imported, XLS is limited to BIFF8; batch- and serial-tracked products are refused by inventory sync.

Compatibility

Test campaigns: 151 unit tests passed, 101 integration tests run on the three tested Dolibarr versions, a full deactivation / reactivation cycle with no data loss, and an HTTP crawl of every module page without a single error. Details are in the compatibility and test files shipped with the module. NextShop Bridge never claims compatibility "with all versions".

Installation and setup

1. Prerequisites: the Third parties, Products and Orders modules enabled; the cURL, OpenSSL and ZipArchive PHP extensions; HTTPS to receive webhooks.
2. In Dolibarr: Home → Setup → Modules → Deploy an external module. On activation, tables, extra fields, mapping templates, permissions, menus and scheduled jobs are created automatically; then grant the permissions and enable the cron.
3. Create a Shopify app with the required scopes, add the store, run the connection test and register the webhooks.
4. Configure the mappings (directions, taxes, gateways, statuses, carriers, warehouses) and the invoicing rule, then start a first synchronization or the migration wizard, beginning with a dry run.

Updates apply versioned, additive-only SQL migrations: no data is ever destroyed.

Support and publisher

NEXT GESTION provides support, installation, configuration, training and additional development. Shipped documentation: user guide, migration guide, synchronization and compatibility matrices, test report.

Published by NEXT GESTION – www.nextgestion.com.

Shopify is a trademark of Shopify Inc. and Dolibarr a trademark of the Dolibarr association; both are cited only to indicate compatibility. NextShop Bridge is neither published nor endorsed by these organizations.

Copyright © NEXT GESTION — www.nextgestion.com — All rights reserved.

Demo of the NextShop Bridge module
Login : demo
Password : demo