WooCommerce Connector | WooCommerce Odoo Integration
Two-way WooCommerce integration over the official REST API: products, customers, orders and stock, with a sync control tower and dry-run safety.
Available for Odoo 16.0, Odoo 17.0, Odoo 18.0, Odoo 19.0. Technical name bambooforge_woocommerce_connector.
WooCommerce Connector | WooCommerce Odoo Integration
A two-way bridge between Odoo 18 and your WooCommerce store: import products, customers and orders, push product changes back, and reconcile refunds — with a resilient job queue, dry-run safety, validation and rollback so you stay in control.
This page is the complete manual. If you follow it top to bottom you can install, connect, run your first sync, automate it, and fix the common issues without contacting support.
Matching the storefront total
A storefront charges shipping and grants discounts outside the product lines, so an order rebuilt from those lines alone is worth less than the order the customer paid for: the sale looks smaller than it was and never reconciles against the platform payout.
With Match Storefront Totals on the instance (on by default):
the shipping charge is imported as its own order line, on a clearly named service product;
whatever still separates Odoo from the platform total — platform discounts, fees, rounding — is posted as a single adjustment line rather than dropped;
the platform total and the remaining difference are stored on the order and shown on its connector tab;
an order that still does not match within Total Tolerance raises a validation warning, so the gap is visible instead of silent.
Imported lines deliberately carry no Odoo tax: the storefront has already computed tax and it is kept on the order's own tax amount field. Switch the option off if you would rather Odoo recompute everything from your own price lists and tax rules.
Overview
The connector keeps Odoo and WooCommerce in sync over the official WooCommerce REST API v3. It covers:
Products — import WooCommerce products into Odoo product templates (optionally with stock, images and tax class), and export Odoo product changes back to the store.
Customers — import WooCommerce customers (and their billing/shipping addresses) into Odoo contacts.
Orders — import WooCommerce orders into Odoo sale orders, mapping each order's WooCommerce status to a sale-order action (keep draft, confirm, cancel, or ignore).
Refunds — optionally discover WooCommerce order refunds and create matching draft customer credit notes in Odoo.
Direction of sync: Odoo ↔ WooCommerce (import is the primary flow; product export and webhook-driven updates are supported).
Every remote call 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.
WooCommerce: live-tested against WooCommerce 10.x; targets the stable REST API v3, so the 8.x–10.x lines are supported. WooCommerce must be reachable from the Odoo server.
Python: no extra libraries beyond a standard Odoo 18 install.
Odoo access: any internal user can use the connector screens. WooCommerce credentials are stored in system-only fields, so only the Settings / Administration user can read or change the Consumer Key and Secret.
Network: outbound HTTPS from Odoo to your store. By default the connector refuses internal/loopback/private hosts as an SSRF safeguard (see Safety features).
Installation
Copy bambooforge_woocommerce_connector into your Odoo addons path.
Restart the Odoo service.
Open Apps, click Update Apps List, search for WooCommerce, and press Activate / Install. Dependencies (Sales, Contacts, Invoicing) install automatically.
No WooCommerce store is required to evaluate the connector: a mock WooCommerce REST API ships inside the module, so you can install, explore and run the full import flow against sample data before pointing it at a real store.
Step 1 — Create REST API keys in WooCommerce
In your WordPress admin:
Go to WooCommerce ▸ Settings ▸ Advanced ▸ REST API.
Click Add key.
Set Description to Odoo, choose the User that owns the key, and set Permissions to Read/Write (Read-only is enough if you only import).
Click Generate API key.
Copy the Consumer key (ck_…) and Consumer secret (cs_…) shown once.
Optional, for real-time updates, you will also create a webhook later (see Automation).
Step 2 — Create the connection in Odoo
Open WooCommerce Connector ▸ Configuration ▸ Instances and create a record.
Key fields:
Field |
What to enter |
|---|---|
Name |
A label for this store, e.g. My Live Store. |
Base URL |
Your store root, e.g. https://store.example.com. |
Authentication |
Consumer Key/Secret over HTTPS (Basic) for HTTPS stores; OAuth 1.0a only for plain-HTTP stores. |
Consumer Key / Secret |
The ck_… / cs_… from Step 1 (visible to administrators only). |
REST Base |
Leave the default wp-json/wc/v3 unless your store differs. |
Verify SSL |
Keep on for production. Turn off only for self-signed test certificates. |
Allow internal host |
Off by default. Turn on only to reach a store on localhost or a private network (lowers the SSRF guard — see Safety features). |
Then click Test Connection. A green Connected state means the credentials and URL are correct. 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 and delete jobs simulate writes: instead of changing data they produce Validation Results you can review under WooCommerce Connector ▸ Operations ▸ Validation Results. This lets you confirm what would happen before anything is written.
To run a first import:
On the instance, click Import Products (and/or Import Customers, Import Orders). This enqueues jobs; it does not block the UI.
Jobs are processed by the WooCommerce Queue Processor scheduled action (every minute), or immediately if you run it manually from Operations ▸ Queue Jobs.
Review Validation Results while still in dry-run.
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 WooCommerce reference so re-imports update the same record instead of duplicating it.
Order status mapping
WooCommerce returns each order's status as a slug (pending, processing, on-hold, completed, cancelled, refunded, failed, checkout-draft). 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:
WooCommerce status |
Default Odoo action |
|---|---|
pending |
Keep draft |
processing |
Confirm sale order |
on-hold |
Keep draft |
completed |
Confirm sale order |
cancelled |
Cancel sale order |
refunded |
Cancel sale order |
failed |
Keep draft |
checkout-draft |
Keep draft |
Change any row to Ignore (do nothing), Keep draft, Confirm sale order or Cancel sale order. Unknown/custom statuses default to Ignore, so a status you have not mapped never triggers a destructive transition. Add a row for any custom status your plugins introduce (use the exact REST slug).
Field mapping & customization
Field Mappings (Configuration) map WooCommerce fields 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 WooCommerce fields per resource. Run Schema Introspection on the instance to refresh it from your live store.
Stock / images / tax are opt-in toggles on the instance: Sync stock, Sync images (and max images), Upload images on export, Sync taxes. They are off by default; turn on only what you need.
Automation (scheduled actions & webhooks)
The module ships these scheduled actions (Settings ▸ Technical ▸ Scheduled Actions):
Scheduled action |
Default |
Purpose |
|---|---|---|
WooCommerce Queue Processor |
every 1 min |
Processes queued import/export/delete jobs. |
WooCommerce Reconciliation |
every 15 min |
Pulls recent remote changes for enabled models. |
WooCommerce Maintenance |
every 1 hr |
Recovers stale/locked jobs and trims old logs. |
WooCommerce Flow Scheduler |
every 5 min |
Runs scheduled sync flows. |
WooCommerce Flow Metrics |
every 1 hr |
Aggregates flow-run metrics. |
WooCommerce Auto Recover |
every 15 min |
Reopens a tripped circuit breaker once the store is healthy. |
Turn on Auto import / Auto reconcile per model on the instance to let the scheduled actions keep things in sync hands-free.
Real-time webhooks (optional): in WooCommerce ▸ Settings ▸ Advanced ▸ Webhooks add a webhook with:
Delivery URL: https://<your-odoo-domain>/woocommerce/webhook
Secret: the instance Webhook Secret (admin-only field on the instance).
Odoo verifies the HMAC-SHA256 signature on each delivery and enqueues a safe import. Without webhooks the scheduled reconciliation still keeps data current.
Safety features
Dry-run mode — simulate writes and review Validation Results before going live.
Business validation profiles — Minimal / Standard / Strict gate risky writes.
Resilient queue — every remote 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 store 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 internal/loopback/private hosts unless Allow internal host is explicitly enabled.
Troubleshooting
Symptom |
Cause and fix |
|---|---|
Test Connection fails with 401 |
Wrong Consumer Key/Secret, or the key lacks permissions. Re-check Step 1; for plain-HTTP stores switch Authentication to OAuth 1.0a. |
"Refused internal/private host" |
Base URL points at localhost/private IP. Enable Allow internal host on the instance (test/self-hosted only). |
SSL errors on Test Connection |
Self-signed certificate. Use a valid cert, or turn off Verify SSL for testing only. |
Orders import but never confirm |
The order's WooCommerce status is mapped to Keep draft or Ignore. Adjust Order State Mappings. |
Jobs stay in Pending |
The Queue Processor is off or the instance is paused. Check Scheduled Actions is active and the instance is not Paused. |
Instance shows Tripped |
Circuit breaker tripped after repeated failures. Fix the store/credentials; Auto Recover reopens it, or click Resume. |
Records imported twice |
Imports are keyed by the WooCommerce reference, so this should not happen. If it does, check that two instances do not point at the same store. |
Nothing happens after Import |
You are in Dry-run. Review Validation Results, then turn dry-run off and re-run. |
For anything else, Operations ▸ Logs records every API call, payload hash 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 WooCommerce 10.x and targets REST API v3, so the 8.x–10.x lines are supported. Validate your exact build with the bundled mock first.
Do I need WooCommerce installed to evaluate it? No. A mock WooCommerce REST API ships inside, so you can install, explore and demo the full import flow before connecting a real store.
How does authentication work? Generate a WooCommerce REST API key (Consumer Key + Secret) under WooCommerce ▸ Settings ▸ Advanced ▸ REST API. Use Basic auth over HTTPS, or OAuth 1.0a signing for plain-HTTP stores — both are built in.
How does real-time sync work? WooCommerce has built-in webhooks. Point one at /woocommerce/webhook with the shared secret; Odoo verifies the signature and enqueues a safe import. Without it, scheduled reconciliation keeps things in sync.
Is it safe to run against production data? 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, orders and refunds from your store and writes the corresponding Odoo records. Credentials are stored in admin-only fields.
In scope today: product/customer/order import, product export, order-status mapping, refund discovery, scheduled sync, signed webhooks.
Out of scope / best-effort: tax auto-matching (off by default, name-based, never auto-creates taxes); multi-warehouse stock routing; subscription/booking order types.
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 / WooCommerce REST v3 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.
Patch upgrades (same series, e.g. 18.0.1.0.0 → later)
Back up your database and filestore first.
Replace the module folder with the newer build.
Restart Odoo with the module updated:
./odoo-bin -c your.conf -u bambooforge_woocommerce_connector -d your_db
Odoo applies any schema/data changes automatically. Your existing records and configuration are preserved.
Cross-version migration (e.g. Odoo 17 → 18)
Upgrading Odoo itself is a database migration handled by Odoo's standard upgrade tooling. When you migrate the database to the next Odoo series, install the matching build of this module for that series. Data created by this module carries over with the database migration.
After any upgrade the module's scheduled actions resume on their normal cadence — no manual re-activation is required.
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.
What is removed
The module's own tables and every record in them (20 models, prefixed woocommerce.*) — this is the data this module created.
The menus, actions, views and reports this module installed.
Its scheduled actions (cron jobs) — they stop immediately on uninstall.
Connection records, credentials, field mappings, queue jobs and sync logs stored in Odoo.
What is preserved
Your remote platform is never touched. Uninstalling only removes the Odoo-side connector; products, customers and orders on the external store/service are untouched.
Records already imported into standard Odoo models (e.g. contacts, products, sales orders) remain — they are ordinary Odoo records once created.
Attachments and chatter messages on standard records are kept.
As always, take a database backup before uninstalling in production.
Changelog
18.0.1.0.0
Current release for Odoo 18.0. This build includes:
Odoo 18 <-> WooCommerce connector: import products, customers and orders via the official WooCommerce REST API (Basic over HTTPS or OAuth 1.0a over HTTP).
Two-way stock sync, live Sync Control Tower, resilient queue and dry-run safety.
Feature additions and fixes ship as new builds on the Odoo Apps store; this page and the module's version reflect the current published release. Always keep the build matched to your Odoo series (see Upgrading & version compatibility).
Screens
