feat(medusa): add Medusa v2 connector

[kiegsgroot]

Add a Medusa (v2) connector

This adds Medusa (the open-source composable-commerce platform, v2) as a first-class connector, built to match the existing Shopify / Amazon / Unicommerce / Zenoti connectors — reusing the shared framework (Ecommerce Item, Ecommerce Integration Log, the controllers/ base classes) rather than introducing anything parallel.

What it does

Flow	Direction	Trigger
Products + variants ↔ Items	both	webhook/poll + Item doc-events
Orders → Sales Orders	Medusa → ERPNext	order.placed (+ scheduled backfill)
Customers + addresses	Medusa → ERPNext	inline on order
Payment captured → Sales Invoice + Payment Entry	Medusa → ERPNext	order.payment_captured
Fulfillment → Delivery Note	Medusa → ERPNext	fulfillment.created
Return → Credit Note (full + partial, qty-prorated tax)	Medusa → ERPNext	order.return_received
Inventory levels	ERPNext → Medusa	scheduled, throttled delta

It follows the Shopify reference closely: a single Medusa Setting doctype owning enable/auth/defaults + warehouse/tax mappings; one HMAC-verified ingestion endpoint that enqueues handlers keyed to an Ecommerce Integration Log; the dummy price-list / tax-category trick to bypass ERPNext re-pricing; and a from_integration guard to avoid push/pull echo loops. It also closes two gaps the others leave open — returns → credit notes (ported from Unicommerce) and optional real price-list pricing.

The one architectural wrinkle

Medusa v2 has no admin API to register webhooks (unlike Shopify's Webhook.create). Events come from server-side subscribers. So the connector ships a small companion subscriber (medusa/medusa_subscriber/, TypeScript) that the merchant installs in their Medusa app; it HMAC-signs and forwards events to the ingestion endpoint. A scheduled poll provides backfill/reconciliation. Open question for reviewers: whether you'd prefer that subscriber to live here, as a docs snippet, or in a separate companion repo — easy to move.

Testing

Integration tests for product, order, inventory and return flows (network-free fake client + JSON fixtures). Verified green against a real ERPNext 16.25 install + a live Medusa v2.4.0 instance — every field mapping was confirmed against the @medusajs/types 2.4.0 definitions. 12 tests pass.

Notes for review

• No new Python dependencies (uses requests, already shipped with Frappe).
• Custom fields are installed on enable and removed on uninstall; a migration patch covers existing sites.
• One incidental commit (fix(tests): make before_tests tax-account creation idempotent) lets the shared test bootstrap run on current ERPNext, which auto-creates the GST account — happy to split this into its own PR.
• Known limitation: the Sales Invoice flow assumes the ERPNext company currency matches the Medusa region currency (the common single-currency setup); multi-currency orders need a customer receivable account in that currency. Documented in the connector README.

Commits

Logically split: framework + Setting → product/customer/order → invoice/fulfillment/returns → inventory → hooks/patches/uninstall → subscriber → tests/docs.

[greptile-apps]

Confidence Score: 4/5

This is close, but the shipping total calculation should be fixed before merging.

• Shipping can be added once per taxed line.
• Shipping can be omitted when the order has no taxable item lines.
• The affected path writes incorrect Sales Order and invoice totals.

Files Needing Attention: ecommerce_integrations/medusa/order.py

_{Reviews (13): Last reviewed commit: "Update ecommerce_integrations/medusa/ret..." | Re-trigger Greptile}

[kiegsgroot]

Thanks for the thorough review — addressed all eight valid findings (one looks like a false positive, noted below). All changes were re-validated against a real ERPNext 16.25 install + Medusa v2.4.0, and the connector test suite (now incl. fulfillment) is green: product 3, order 5, inventory 2, returns 3, fulfillment 4.

#	Finding	Resolution
2 (P1)	Discounts didn't reduce totals	Net the per-unit discount into the SO/SI rate so totals match the Medusa order total (869d852). Added an assertion on grand_total.
1 (P1, sec)	Import endpoints lacked authz	frappe.only_for("System Manager") on every whitelisted import method (ef2fae0).
5 (P1)	Created products lost their link	Link-insert failures are surfaced as an Error log instead of being swallowed as success (ef2fae0).
3 (P1)	Partial fulfillment shipped wrong rows	Match strictly on the Medusa order line id; removed the ship-one-qty-everywhere / ship-whole-order fallbacks; an unmatched fulfillment now raises rather than moving wrong stock (107eb22). Added full/partial/unmatched tests.
4 (P2)	Variant SKU collided with Items	A variant whose SKU already exists as an Item is now linked instead of duplicate-inserted (ef2fae0).
8 (P2)	Backfill dropped paid/fulfilled state	Backfill replays SI/Payment/DN (and cancellation) for historical orders, committing the SO first so a replay failure can't roll it back (869d852). Added a backfill test.
7 (P2)	Missing variant advanced the watermark	A not-found SKU lookup no longer advances inventory_synced_on, so a transient empty result retries (ef2fae0).
6 (P2)	Re-import hid new variants	Bulk import now reconciles every variant, not just the template, so a product that gained a variant is re-synced (ef2fae0).
9 (P2)	Tax proration divides by zero	I believe this is already guarded: the per-item path does full_qty = …; if not full_qty: … continue before the division (returns.py), so a zero/None full qty is skipped. Happy to add an explicit comment if you'd still like it clearer.

🤖 Generated with Claude Code

[kiegsgroot]

Thanks — addressed all three, and the fulfillment one turned out to be the tip of a bigger event-layer issue worth fixing together. Re-validated against ERPNext 16.25 + Medusa v2.4.0 (suite now 19 green incl. the two new cases below).

Finding	Resolution
Fulfillment payload mismatch (fulfillment.py)	Switched to the order-scoped order.fulfillment_created event (fulfillment.created carries only a fulfillment id). The handler now resolves the full order from an {order_id, fulfillment_id} payload, and the subscriber forwards the order (b860f32). While verifying against Medusa v2.4.0 I also found order.payment_captured isn't a real event (only order.completed exists) and that order.fulfillment_created/order.return_received carry order_id/return_id rather than id — so the subscriber now extracts the right id per event and forwards the order (or {order_id, return}).
Disabled webhooks still run (connection.py)	process_request now returns early (logging Invalid) when the integration is disabled, so a stale subscriber can't drive handlers as Administrator — applied your suggested guard (bd8beaa). Added a test.
Lookup 404 advances watermark (inventory.py)	Split the SKU lookup from the location-level update: a lookup failure (incl. a transient 404) no longer advances inventory_synced_on (it retries); only a 404 from the location-level update marks the row synced (3122ad5).

🤖 Generated with Claude Code

[kiegsgroot]

Addressed all three — re-validated against ERPNext 16.25 + Medusa v2.4.0 (suite now 22 green across 7 modules).

Finding	Resolution
Invoice before capture (constants.py/invoice)	prepare_sales_invoice now checks the order's payment_collections for a captured payment before creating the Sales Invoice + Payment Entry, so an order.completed for an uncaptured order is no longer recorded as paid. The backfill path shares the same gate (2fceb41). Added a test.
Webhook ordering drops state (connection.py)	Downstream handlers no longer give up with Invalid when the Sales Order/Invoice is missing — they ensure it from the order first (idempotently), so order.completed / order.fulfillment_created / order.return_received / order.canceled arriving before order.placed finishes still produce the invoice, delivery note, credit note, or cancellation (2fceb41). Added an out-of-order test.
Location fetch cannot save (medusa_setting.py)	fetch_medusa_locations no longer calls self.save() (which validate() rejects for rows without a warehouse). It appends the rows and lets the client refresh the table — the operator maps warehouses and saves the form, matching the Shopify connector (c4a22c6). Added a test.

🤖 Generated with Claude Code

[kiegsgroot]

Both addressed — re-validated against ERPNext 16.25 + Medusa v2.4.0 (suite 23 green).

Finding	Resolution
Draft orders block replay (order.py)	ensure_sales_order now submits a pre-existing draft Sales Order (left by a failed run or manual import) instead of skipping on sync_sales_order's id dedup. So invoice / fulfillment / return / cancel replay is no longer blocked when a draft with the Medusa id exists (55791e7). Added a test.
Check setting permission (medusa_setting.py)	fetch_medusa_locations now calls self.check_permission("write") before making credentialed Medusa calls and replacing the warehouse-mapping table, so only users who can write the Medusa Setting can invoke it (55791e7).

🤖 Generated with Claude Code

[kiegsgroot]

Both addressed — re-validated against ERPNext 16.25 + Medusa v2.4.0 (suite 24 green).

Finding	Resolution
Backfill skips returns (order.py)	The historical replay now replays returns as credit notes too — using the order's embedded returns when present, otherwise fetching them from Medusa — so a returned historical order isn't left billed/fulfilled with overstated accounting. Added a backfill credit-note assertion.
Unmatched returns overcredit (returns.py)	When a return names items but none match a credit-note row, the handler now raises (fail-safe) instead of treating it as a full return and crediting every invoice line. Added a test that an unmatched return produces no credit note.

🤖 Generated with Claude Code

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Try greploops.

[greptile-apps]

Shipping Added Per Taxed Line _add_shipping() runs inside the line-item tax loop. A two-line order with tax on both lines appends the same shipping charge twice, while an order with no taxable lines never appends shipping at all, so the Sales Order and later invoice can overcharge or drop shipping.

Rule Used: What: Ignore the pull request description and eval... (source)