The ERPNext Medusa Integration installs a set of custom doctypes that store configuration, log API activity, manage storefront content, and extend core ERPNext doctypes with Medusa-specific fields. This page catalogues every doctype created by the integration and describes the custom fields added to standard ERPNext doctypes.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.
Configuration and logging
Medusa Configuration
A Single doctype (one record per site) that holds all settings required for the integration to connect to a Medusa backend:
- Medusa API base URL
- Admin email and password used for authentication
- An Enable checkbox that acts as a global on/off switch for all outbound API calls
Medusa Request Log
An append-only log doctype. Every call made through the send_request() utility in utils.py automatically creates one record here with the following fields:
| Field | Description |
|---|---|
status | "Success" if the HTTP response was OK, "Failure" otherwise |
payload | JSON-serialised request body sent to Medusa |
response | JSON-serialised response body (or raw text on failure) |
voucher_type | Doctype of the ERPNext document that triggered the call (e.g., "Sales Order") |
voucher_name | Name of the ERPNext document that triggered the call |
voucher_type or status to find the relevant entry.
Homepage and storefront content
Homepage Landing
A Single doctype that controls the top-level storefront homepage. Key fields include:
delivery_charges— flat delivery charge applied to non-Muscat ordersprice_visibility_threshold— items with a standard price below this value show the price to all visitors; items at or above it show0(price on request)- Child tables for the top section, menu section, and other homepage layout areas
Homepage Banner
Stores individual banner records (image, link, title) used in homepage carousel or hero sections.
Homepage Item
Stores featured item entries displayed on the homepage.
Homepage Order
Controls the display order of sections on the homepage.
Product collections
Product Collection
A Single doctype with four child tables — one per top-level product category (Dental, Medical, Infection Control, Medical Laboratory IVD). Each child table is refreshed nightly by the add_top_selling_items_to_collection scheduled task with the top 20 best-selling items for that category.
Product Collection Item
The child table doctype used by Product Collection. Each row stores an item_code, item_name, and sales_count.
Customer and order support
Medusa Wishlist
A child table doctype used inside Website Item. Each row stores a medusa_customer_id, representing one customer who has wishlisted the parent item. The handle_wishlist API endpoint adds and removes rows in response to storefront actions.
Website Coupon Code
Stores coupon codes that can be applied during checkout on the Medusa storefront.
Email OTP
Stores one-time password records for storefront authentication. Each record includes the OTP value, associated email address, expiry time, and a used/expired status flag. The expire_otps scheduled task cleans up stale records every minute.
Opportunity Contact
A supporting child table that stores contact details associated with an opportunity or quotation.
Returned Sales Order Item
A child table that records items from a sales order that have been returned.
Increased Items
A child table that tracks items whose quantities were increased during the order review / quotation negotiation workflow.
Item and Brand Entry
A supporting table for associating items with specific brands in various contexts.
Reviews and ratings
Website Item Review
A child table used inside Website Item (as custom_review). Each row stores a customer’s review of the product:
| Field | Description |
|---|---|
medusa_id | Medusa customer ID of the reviewer |
name1 | Display name of the reviewer |
review | Review text |
review_id | Medusa-side review identifier |
rating | Normalised rating (0–1 scale, where 1 = 5 stars) |
date | Review date |
likes / dislikes | Aggregate like/dislike counts |
custom_overall_rating, which is recalculated as a weighted average whenever a review is added or updated.
Clearance and deals
Best Deals
Stores items currently on sale or in a best-deals promotion, updated nightly by fetch_clearance_items.
Expiring Items
Parent doctype for the clearance/expiry tracking feature.
Expiring Items Table
Child table of Expiring Items. Each row represents one item approaching its expiry date.
Storefront content blocks
Product Details Banner
Stores promotional banner content displayed on individual product pages.
Product Suggestions
Stores curated product suggestion sets for upsell/cross-sell sections.
Testimonial
Stores customer testimonials displayed on the storefront.
Youtube Videos
Stores YouTube video entries (URL, title, description) for embedding in storefront pages.
Custom fields on standard ERPNext doctypes
In addition to new doctypes, the integration adds custom fields to several existing ERPNext doctypes. These fields carry the Medusa identifier for each record, enabling the integration to correlate ERPNext data with Medusa data:| Doctype | Custom field | Purpose |
|---|---|---|
| Customer | medusa_id | Medusa customer ID |
| Lead | medusa_id | Medusa customer ID (before conversion) |
| Website Item | medusa_id | Medusa product ID |
| Website Item | medusa_variant_id | Medusa product variant ID |
| Website Item | custom_overall_rating | Computed average review rating |
| Website Item | custom_skip_update_hook | Internal flag to suppress sync on a single save |
| Website Item | custom_parent_website_item | Link to parent item for variant grouping |
| Item Price | medusa_id | Medusa price list ID |
| Item Price | medusa_price_id | Medusa price entry ID within the price list |
| Item Group | medusa_id | Medusa collection ID |
| Item Group | custom_medusa_route | Computed URL route used by the storefront |
| Sales Order | medusa_order_id | Medusa order ID |
| Sales Order | from_ecommerce | Flag indicating the order originated from the storefront |
| Quotation | medusa_draft_order_id | Medusa draft order ID |
| Quotation | medusa_quotation_id | Medusa quotation ID |
| Quotation | medusa_order_id | Medusa order ID after approval |
| Quotation | from_ecommerce | Flag indicating the quotation originated from the storefront |
| Sales Invoice | medusa_order_id | Inherited from the source Sales Order |
| Sales Invoice | from_ecommerce | Inherited from the source Sales Order |
The
medusa_id field is the primary link between ERPNext and Medusa. If this field is blank on a record, the integration will attempt to create a new corresponding record in Medusa rather than updating an existing one.