nopCommerce Connector

Overview

The connector imports data from nopCommerce into Odoo by reading the nopCommerce MySQL database directly (via the pymysql library) with the credentials you supply. nopCommerce has no built-in REST API, so there is no API key to generate and no plugin to install on the store side — only read access to the database. It covers:

• Products — import nopCommerce products into Odoo product templates (name, SKU, price, categories; optionally stock and image URLs).

• Customers — import nopCommerce customers (name, email, company, phone, role) into Odoo contacts.

• Orders — import nopCommerce orders into Odoo sale orders (line items, totals, payment method), mapping each order's nopCommerce status to a sale-order action (keep draft, confirm, cancel, or ignore).

Direction of sync: Odoo ← nopCommerce (import only). The connector is read-only: it never writes to, updates, or deletes anything in nopCommerce, and nopCommerce never pushes to Odoo. Synchronisation runs on a schedule, like a database mirror. Money is read verbatim — nopCommerce stores decimal major units.

Every database read goes through a queue: nothing is written to Odoo until a job runs, jobs retry with back-off on transient failures, and a circuit breaker pauses an instance that keeps failing.

Requirements

• Odoo: 18.0, Community or Enterprise.

• nopCommerce: live-tested against nopCommerce 4.80 on MySQL/MariaDB. The connector reads the standard nopCommerce schema (PascalCase tables/columns), so the 4.x line on MySQL is supported. The MySQL server must be reachable from the Odoo server.

• Python: the Odoo server needs the pymysql library (pip install pymysql). It is the only extra dependency; without it the connector cannot open a database connection and Test Connection fails with a clear message.

• Odoo access: any internal user can use the connector screens. The MySQL User and Password are stored in system-only fields, so only the Settings / Administration user can read or change them.

• Network: direct TCP connectivity from the Odoo server to the nopCommerce MySQL port (default 3306). By default the connector refuses internal/loopback/private storefront hosts as an SSRF safeguard (see Safety features).

Installation

1. Install the pymysql Python library on the Odoo server (pip install pymysql) and restart Odoo so it is importable.

2. Copy bambooforge_nopcommerce_connector into your Odoo addons path.

3. Restart the Odoo service.

4. Open Apps, click Update Apps List, search for nopCommerce, and press Activate / Install. Dependencies (Sales, Contacts, Invoicing) install automatically.

No live nopCommerce store is required to evaluate the mapping: a bundled set of nopCommerce-row-shaped mock fixtures lets you install the module, run schema introspection and explore the field mappings against sample data. Running a real import, however, needs a reachable MySQL database (see Step 1).

Step 1 — Grant read-only access to the nopCommerce MySQL database

The connector authenticates by connecting to the nopCommerce database, so the first step is on your database server, not in the nopCommerce admin. Create a dedicated MySQL user that can only read the nopCommerce database, and make sure the Odoo server can reach it over the network.

1. Open a MySQL/MariaDB client (e.g. mysql CLI, phpMyAdmin) as an administrator on the server that hosts the nopCommerce database.

2. Create a read-only user and grant it SELECT on the nopCommerce database only. Replace the database name, username, password and host to match your setup:

   CREATE USER 'odoo_ro'@'%' IDENTIFIED BY 'a-strong-password';
   GRANT SELECT ON nopcommerce.* TO 'odoo_ro'@'%';
   FLUSH PRIVILEGES;

   Grant SELECT only — the connector never needs INSERT, UPDATE or DELETE. A read-only grant is the safest way to guarantee nopCommerce is never modified. If your Odoo server has a fixed IP, replace '%' with that IP for a tighter grant (e.g. 'odoo_ro'@'10.0.0.5').

3. Allow the connection over the network:

   • Make sure MySQL listens on an address the Odoo server can reach (check bind-address in my.cnf; 127.0.0.1 only allows connections from the same host).

   • Open the MySQL TCP port (default 3306) in any firewall between the Odoo server and the database server.

   • If Odoo and nopCommerce share one host, the database is reachable at 127.0.0.1:3306 — but note that a loopback/private host triggers the SSRF guard on the storefront URL (see Step 2 and Safety features).

4. From the Odoo server, confirm the user can connect and read, for example:

   mysql -h <db-host> -P 3306 -u odoo_ro -p nopcommerce -e "SELECT 1;"

   A clean 1 means the credentials, network path and port are correct.

Step 2 — Create the connection in Odoo

Open nopCommerce Connector ▸ Configuration ▸ Instances and create a record.

Key fields:

Then click Test Connection. The connector opens a database connection and runs SELECT 1. A green Connected state means the host, port, database name and credentials are correct. On the first successful connect, the default order-status mapping table is seeded automatically. If it fails, the exact error is shown on the form and recorded in Logs (see Troubleshooting).

Tip: use Quick Setup (button on the instance) to pick a use case (catalog only, B2C full sync, …), seed default field mappings and order-status rules, and apply a recommended schedule in one step.

Step 3 — First sync (dry-run, then live)

New instances start with Dry-run ON. In dry-run, import jobs simulate writes: instead of changing data they produce Validation Results you can review under nopCommerce Connector ▸ Operations ▸ Validation Results. This lets you confirm what would happen before anything is written.

To run a first import:

1. On the instance, click Import Products (and/or Import Customers, Import Orders). This enqueues jobs; it does not block the UI.

2. Jobs are processed by the Nopcommerce Queue Processor scheduled action (every minute), or immediately if you run it manually from Operations ▸ Queue Jobs.

3. Review Validation Results while still in dry-run.

4. When satisfied, open the instance, turn Dry-run OFF, and run the imports again to write the records for real.

Imported records land in the standard Odoo apps: Sales ▸ Products, Contacts, and Sales ▸ Orders. Each carries its nopCommerce reference so re-imports update the same record instead of duplicating it.

Order status mapping

nopCommerce stores each order's status as a numeric OrderStatusId, which the connector normalizes to a status slug (pending, processing, complete, cancelled). Under Configuration ▸ Order State Mappings each instance gets a default table that decides what happens to the Odoo sale order when an order arrives in a given status:

Change any row to Ignore (do nothing), Keep draft, Confirm sale order or Cancel sale order. Unknown/unmapped statuses default to Ignore, so a status you have not mapped never triggers a destructive transition.

Field mapping & customization

• Field Mappings (Configuration) map nopCommerce columns to Odoo fields per model. Use Generate suggested mappings on the instance to seed the business-critical ones, then adjust. The mapping board flags fields that need attention.

• Schema Fields lists the discovered nopCommerce columns per resource. Run Schema Introspection on the instance to refresh it (it samples live rows; if the database is unreachable it falls back to the bundled sample row so you can still review the mapping).

• Stock / images / tax are opt-in toggles on the instance: Sync stock (reads StockQuantity), Sync images (and max images), Sync taxes / Auto-match taxes (best effort, name-based, never auto-creates taxes). They are off by default; turn on only what you need.

Automation (scheduled actions)

Sync is schedule-driven only. nopCommerce has no REST API and emits no events, so there are no real-time webhooks — the connector polls the database on a cron, like a database mirror. The module ships these scheduled actions (Settings ▸ Technical ▸ Scheduled Actions):

Turn on Auto import / Auto reconcile per model on the instance to let the scheduled actions keep things in sync hands-free.

Safety features

• Read-only by design — the connector only ever runs SELECT queries against nopCommerce; it never writes, updates or deletes there. Use a read-only MySQL grant (Step 1) to enforce this at the database level.

• Dry-run mode — simulate writes and review Validation Results before going live.

• Business validation profiles — Minimal / Standard / Strict gate risky writes into Odoo.

• Resilient queue — every read/import action is a job with retry and exponential back-off.

• Circuit breaker — after repeated failures an instance auto-pauses (Tripped); the Auto Recover action reopens it once the database responds again.

• Rollback snapshots — when enabled, imports capture a snapshot so you can undo a batch from Operations ▸ Rollback Snapshots.

• SSRF guard — the connector refuses an internal/loopback/private storefront Base URL unless Allow internal host is explicitly enabled.

Troubleshooting

For anything else, Operations ▸ Logs records every database read and error with a timestamp.

Frequently asked questions

Which versions are supported? Odoo 18.0 on the Odoo side. On the store side the connector was live-tested on nopCommerce 4.80 on MySQL/MariaDB and reads the standard 4.x schema. Validate your exact build with the bundled sample fixtures first.

Do I need nopCommerce installed to evaluate it? Not for the mapping. Bundled nopCommerce-row-shaped sample fixtures let you install the module, run schema introspection and explore the field mappings. A real import needs a reachable MySQL database.

How does authentication work? There is no API key. nopCommerce has no REST API, so the connector connects to the nopCommerce MySQL database with read-only credentials (host, port, database, user, password). Generate those credentials on your database server (see Step 1).

Does this write anything back to nopCommerce? No. The connector is read-only: it only runs SELECT queries and never writes, updates or deletes in nopCommerce. Use a read-only MySQL grant to enforce this at the database level.

How does real-time sync work? There is no real-time/webhook path — nopCommerce has no REST API and emits no events. Sync is scheduled: the connector polls the database on a cron (every minute for the queue, every 15 minutes for reconciliation). Tighten the cron interval if you need fresher data.

Is it safe to run against production data? Yes. It only reads nopCommerce. On the Odoo side, dry-run is ON by default, validation blocks risky writes, and rollback snapshots let you undo. You decide when to go live.

What support and refund policy do I get? Every request is answered within 24 hours, setup help included. If you report a bug within 2 months of purchase and it is not resolved within 15 days, you are entitled to a full money-back refund.

Data, privacy & limits

• The connector reads products, customers and orders from the nopCommerce MySQL database and writes the corresponding Odoo records. The MySQL credentials are stored in admin-only fields.

• Read-only: the connector never writes to, updates or deletes anything in nopCommerce. It opens the database connection only to run SELECT queries.

• In scope today: product/customer/order import, order-status mapping, scheduled sync, dry-run, validation and rollback.

• Out of scope / roadmap: refund/credit-note import and inbound webhooks are not yet supported. Export back to nopCommerce is not supported (read-only by design). Tax auto-matching is best-effort, name-based and never auto-creates taxes; multi-warehouse stock routing is not handled.

Support & updates

• Support: support@bambooforge.dev — answered within 24 hours, setup help included.

• Refund: report a bug within 2 months of purchase; if unresolved within 15 days, full refund.

• Full source is included. Updates track the supported Odoo 18 / nopCommerce 4.x line.

Upgrading & version compatibility

This build targets Odoo 18.0. Each Odoo major series (17.0, 18.0, 19.0) has its own dedicated build of this module — always install the build that matches your Odoo version. Mixing a build with a different Odoo series is not supported.

Uninstallation

You can remove this module at any time from Apps → (this module) → Uninstall, or from the command line. Uninstalling is clean and reversible by reinstalling — but note what is and is not deleted.

Changelog