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.

This page documents the endpoints and document events that keep ERPNext Item Groups in sync with Medusa collections and expose the group hierarchy to the storefront’s navigation menus.

​
GET get menu

GET /api/method/medusa_integration.api.get_menu Returns a hierarchical Item Group tree for use in storefront navigation menus. The response depth varies depending on the mobile_view flag.

​
Parameters

​
parent
string
required
Name of the ERPNext Item Group to use as the root of the returned tree.
​
mobile_view
number
default:"0"
Pass 1 to return the full group hierarchy with thumbnails. Pass 0 (default) to return only one level of children and no thumbnails.

​
Response

​
title
string
Display name of the Item Group.
​
handle
string
URL-safe slug generated from the group name (lowercase, hyphens replacing non-alphanumeric characters).
​
url
string
Value of the custom_medusa_route field on the Item Group document. Only populated when mobile_view=1.
​
thumbnail
string
Absolute URL of the group image. Only populated when mobile_view=1. null if no image is attached.
​
childCount
number
Number of direct child Item Groups.
​
children
array
Recursive array of child group objects. In mobile_view=0, only one level deep. In mobile_view=1, full depth.
Children are sorted by childCount descending so that groups with the most sub-categories appear first.

​
Example

curl 'https://your-erpnext.example.com/api/method/medusa_integration.api.get_menu?parent=Dental&mobile_view=0'
Response (mobile_view=1)
{
  "title": "Dental",
  "handle": "dental",
  "url": "products/dental",
  "thumbnail": "https://your-erpnext.example.com/files/dental.png",
  "childCount": 3,
  "children": [
    {
      "title": "Dental Equipment",
      "handle": "dental-equipment",
      "url": "products/dental/dental-equipment",
      "thumbnail": "https://your-erpnext.example.com/files/dental-equipment.png",
      "childCount": 2,
      "children": [...]
    }
  ]
}

​
GET update all item groups

GET /api/method/medusa_integration.api.update_all_item_groups Recalculates the custom_medusa_route field on every Item Group in ERPNext using the full group hierarchy. This endpoint requires authentication.
Run this after reorganizing Item Groups in ERPNext — for example after renaming a group or changing its parent — to ensure all storefront URLs remain consistent.
No request parameters.

​
Route format

Routes are built by walking up the parent chain to the Products root group and joining slugified names with /: 
products/{parent-group}/{child-group}
For example, an Item Group named Dental Equipment inside Dental inside Products gets the route: 
products/dental/dental-equipment

​
Response

​
status
string
"success" on completion, "error" if an exception occurred.
​
message
string
Human-readable result message.
curl --request GET \
  --url 'https://your-erpnext.example.com/api/method/medusa_integration.api.update_all_item_groups' \
  --header 'Authorization: token api_key:api_secret'
Response
{
  "status": "success",
  "message": "All item groups updated successfully."
}

​
Automatic collection export on Website Item save

When a Website Item is saved and its Item Group does not yet have a medusa_id, export_item_group() is called automatically to push the Item Group to Medusa as a collection. This is triggered by the validate document event on Website Item:
hooks.py
doc_events = {
    "Website Item": {
        "validate": "medusa_integration.api.website_item_validate"
    },
    ...
}

​
What happens

  1. The Website Item’s item_group is checked for a medusa_id.
  2. If none exists, a POST /admin/collections request is sent to Medusa.
  3. The returned collection ID is stored in medusa_id on the Item Group doctype.
  4. update_all_item_groups() is called to refresh custom_medusa_route on all groups.

​
Medusa request payload

{
  "title": "Dental Equipment",
  "metadata": {
    "parent_item_group": "Dental",
    "is_group": 1
  }
}
export_item_group() is a no-op if the Item Group already has a medusa_id. It will not overwrite an existing collection.

Build docs developers (and LLMs) love

Get started for freeTalk to us