Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aerele/medusa_integration/llms.txt

Use this file to discover all available pages before exploring further.

The ERPNext Medusa Integration is a Frappe app that bridges your ERPNext instance and a Medusa headless eCommerce backend. It keeps products, orders, inventory, customers, and pricing synchronized between both platforms so your operations team works in ERPNext while your customers shop through a Medusa-powered storefront — with no manual data entry between them.

Quickstart

Install via bench and complete your first product sync in under 10 minutes.

Configuration

Set your Medusa backend URL, admin credentials, and coupon discount rules.

Sync guides

Understand how products, orders, inventory, customers, and prices stay in sync.

API reference

Explore the whitelisted endpoints the integration exposes to your Medusa storefront.

​
Key features

  • Product sync — Save a Website Item in ERPNext and it is pushed to Medusa’s product catalog automatically, including descriptions, specifications, and images.
  • Order lifecycle — Customer orders in Medusa trigger Quotations and Sales Orders in ERPNext; Invoices, Delivery Notes, and Payment Entries are pushed back to Medusa as fulfillment progresses.
  • Inventory updates — Stock levels are exported to Medusa on a daily schedule so your storefront reflects real availability.
  • Customer management — Leads and Customers created through Medusa are synced to ERPNext with their Medusa IDs for two-way lookup.
  • Price management — Standard Selling price lists and customer-specific prices are exported to Medusa price lists, including clearance and top-selling collections.
  • Coupon discounts — Optional coupon discount rules (minimum cart value, discount amount, expiry date) can be enabled and pushed to Medusa.

​
Architecture overview

The integration relies on two mechanisms:
  1. Document events — Frappe hooks fire whenever key doctypes (Website Item, Sales Order, Sales Invoice, Delivery Note, Payment Entry, Quotation, Item Price) are created, updated, or submitted. Each hook calls the corresponding Medusa API to keep data in sync.
  2. Scheduled tasks — A cron job runs every minute to process quotation emails and expire OTPs. A nightly job (01:00) bulk-exports items and images, syncs missing prices, fetches clearance items, and updates top-selling collections. Stock levels are updated once per day via the daily_long schedule.
Authentication with the Medusa Admin API uses a Bearer token stored in the Medusa Configuration doctype. The token is obtained automatically using the admin email and password you provide, and is refreshed transparently whenever a request returns 401 Unauthorized.

​
Prerequisites

Before installing the ERPNext Medusa Integration, make sure you have the following:
  • ERPNext v15+ running on a Frappe bench (Python 3.10 or higher required).
  • Frappe bench installed and configured with at least one active site.
  • A running Medusa backend (v1.x or compatible) with an admin user account.
  • Network access from your ERPNext server to your Medusa backend URL.
The Medusa Configuration doctype is accessible only to users with the System Manager role. Ensure the user who performs initial setup has this role assigned.
The app is installed through the standard bench workflow — no manual file copying or database changes are required. See the Quickstart for step-by-step installation instructions.

Build docs developers (and LLMs) love

Get started for freeTalk to us