Medusa Connector

Overview

The connector keeps Odoo and Medusa in sync over the Medusa Admin API, using a JSON REST client that speaks both the Medusa v2 and Medusa v1 lines. A capability layer absorbs the route and money-unit differences between them (v2 uses major currency units, v1 uses minor units / cents). It covers:

• Products — import Medusa products (with variants, options and images) into Odoo product templates, optionally with stock and tax, and export Odoo product changes back to the store.

• Customers — import Medusa customers and their addresses into Odoo contacts.

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

• Refunds — optionally discover Medusa order_slip credit notes attached to an order and create matching draft customer credit notes in Odoo.

Direction of sync: Odoo ↔ Medusa (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.

• Medusa: both Medusa v2 and Medusa v1 are supported; pick the matching line in the API version field. The Medusa server 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. Medusa credentials are stored in system-only fields, so only the Settings / Administration user can read or change the API key, password, publishable key and webhook secret.

• Network: outbound HTTP/HTTPS from Odoo to your Medusa server. By default the connector refuses internal/loopback/private hosts as an SSRF safeguard (see Safety features).

Installation

1. Copy bambooforge_medusa_connector into your Odoo addons path.

2. Restart the Odoo service.

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

No Medusa store is required to evaluate the connector: a mock Medusa Admin 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. Point the instance Base URL at <your-odoo>/medusa/mock_api with auth type Email + Password (any email/password is accepted) to try it.

Step 1 — Get Medusa Admin API access

The connector authenticates to the Medusa Admin API. Choose one of three auth types on the Odoo instance; how you obtain the credential depends on your Medusa line:

Medusa v2 — Admin Secret API Key (recommended)

1. Sign in to the Medusa Admin dashboard as an admin user.

2. Go to Settings ▸ Secret API Keys (Developer / API key management).

3. Create a Secret API Key, give it a name like Odoo, and copy the key once it is shown.

4. In Odoo, set Authentication to Admin Secret API Key (v2) and paste the key into API Key. The connector sends it as HTTP Basic (key as username, empty password).

Medusa v2 — Email + Password (JWT)

If you prefer not to manage a secret key, set Authentication to Email + Password (JWT) and enter an admin Email and Password. The connector exchanges them for a JWT at POST /auth/user/emailpass and caches the token.

Medusa v1 — Email + Password or pre-issued token

For a Medusa v1 server, set API version to Medusa v1. Either use Email + Password (JWT) (the connector logs in at POST /admin/auth/token), or, if you already hold a token, set Authentication to Bearer Token and paste it into API Key.

Optional: if your Medusa requires a publishable key for store-scoped calls, paste it into Publishable API Key; it is sent as the x-publishable-api-key header.

Step 2 — Create the connection in Odoo

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

Key fields:

Then click Test Connection. A green Connected state means the credentials and URL are correct. On the first successful connection the default order-status mapping 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 solution pack (catalog only, B2C full sync, B2B order-first, retail starter), seed default field mappings and flows, and apply a recommended safety profile 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 Medusa 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 Medusa 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 Medusa reference (a binder record) so re-imports update the same record instead of duplicating it.

Order status mapping

Medusa exposes each order's status (e.g. pending, completed, archived, canceled, requires_action) and a fulfillment_status (e.g. not_fulfilled, fulfilled, shipped, returned) used as a fallback. Under Configuration ▸ Order State Mappings each instance gets a default table (seeded on first successful connection) 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/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 store introduces (use the exact Medusa status string).

Field mapping & customization

• Field Mappings (Configuration) map Medusa 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 Medusa fields per resource. Run Schema Introspection on the instance to refresh it from your live store (it falls back to the bundled mock sample if the store is unreachable).

• Stock / images / tax / refunds are opt-in toggles on the instance: Sync stock, Sync images (and max images), Upload images on export, Sync taxes / Auto-match taxes on import, Sync refunds / Auto-post refund. They are off by default; turn on only what you need. Tax auto-matching is name-based, company-scoped, and never auto-creates taxes.

Automation (scheduled actions & webhooks)

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.

Real-time webhooks (optional): install the subscriber companion (see Installation). It POSTs HMAC-SHA256-signed events to:

• Delivery URL: https://<your-odoo-domain>/medusa/webhook (optionally ?instance_id=<id> to target a specific instance).

• Secret: the instance Webhook Secret (admin-only field on the instance).

Each delivery carries an X-Medusa-Signature header. Odoo verifies the HMAC-SHA256 signature over the raw body, rejects stale or replayed deliveries, 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 (field Dry-run mode, ON by default).

• Business validation profiles — Minimal / Standard / Strict gate risky writes (field Business validation profile).

• Safety profile — Conservative / Balanced / Aggressive presets set the dry-run, validation, batch-size and webhook dials in one click.

• Resilient queue — every remote action is a job with retry, exponential back-off and a dead-letter state.

• Circuit breaker — after repeated failures an instance auto-pauses (Tripped); the Auto Recover action reopens it once the store responds again (auth/configuration failures trip it immediately and require manual resume).

• Rollback snapshots — when Rollback enabled is on, 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.

• Signed webhooks — the public webhook route fails closed: a missing secret or signature is rejected, and stale/replayed deliveries are dropped.

Troubleshooting

For anything else, Operations ▸ Logs records every API call and error with a timestamp.

Frequently asked questions

Which versions are supported? Odoo 18.0 on the Odoo side. On the store side both Medusa v2 and Medusa v1 are supported — pick the line in the API version field. Validate your exact build with the bundled mock first.

Do I need a Medusa store to evaluate it? No. A mock Medusa Admin API ships inside. Point the Base URL at <your-odoo>/medusa/mock_api (auth Email + Password, any credentials) to run the full import flow before connecting a real store.

How does authentication work? Three ways: a Medusa v2 Admin Secret API Key (sent as HTTP Basic), a pre-issued Bearer Token, or Email + Password exchanged for a JWT (/auth/user/emailpass on v2, /admin/auth/token on v1). All three are built in.

How does real-time sync work? Install the bundled webhook subscriber companion in your Medusa project. It POSTs HMAC-SHA256-signed events to /medusa/webhook; 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 (order_slip) from your Medusa store and writes the corresponding Odoo records. Credentials are stored in admin-only fields.

• In scope today: product/variant/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 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 / Medusa v1 & v2 Admin API 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