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.

These endpoints handle customer-facing wishlist management, product reviews, and personalised product recommendations. All endpoints are guest-accessible and accept a Medusa customer ID for personalised responses.

​
Handle wishlist

POST Guest 
POST https://<erpnext-site>/api/method/medusa_integration.api.handle_wishlist
Adds or removes one or more products from a customer’s wishlist. The wishlist is stored as a child table (custom_medusa_wishlist) on the Website Item, keyed by medusa_customer_id. Each item in the request is processed independently and returns its own status.
is_add and is_remove are mutually exclusive. Sending both as 1 or both as 0 returns an error.

​
Request body

​
item_codes
string | string[]
required
One or more Medusa product IDs to process. A single string is treated as a one-item list.
​
customer_id
string
required
Medusa customer ID of the wishlist owner.
​
is_add
integer
default:"0"
Set to 1 to add items to the wishlist. Mutually exclusive with is_remove.
​
is_remove
integer
default:"0"
Set to 1 to remove items from the wishlist. Mutually exclusive with is_add.

​
Response

Returns an array with one entry per item code processed.
​
item_code
string
The Medusa product ID that was processed.
​
status
string
Result for this item: "success", "skipped", or "error".
​
message
string
Human-readable description of the result. Examples:
  • "Customer added to wishlist"
  • "Customer removed from wishlist"
  • "Customer already in wishlist" (when adding a duplicate)
  • "Customer not in wishlist" (when removing a non-existent entry)
  • "Item not found" (when the Medusa ID does not match any Website Item)

​
Example

curl --request POST \
  --url "https://erp.example.com/api/method/medusa_integration.api.handle_wishlist" \
  --header "Content-Type: application/json" \
  --data '{
    "item_codes": ["prod_01ABC", "prod_02DEF"],
    "customer_id": "cus_01HXYZ",
    "is_add": 1,
    "is_remove": 0
  }'

​
Add review to website item

POST Guest 
POST https://<erpnext-site>/api/method/medusa_integration.api.add_review_to_website_item
Adds a new product review or updates an existing one for a Medusa customer. If the customer already has a review for the product (matched by customer_id), the review is updated in place. The custom_overall_rating on the Website Item is recalculated after every save. Ratings are stored internally as rating / 5 (a 0–1 float) but accepted as integers 1–5.
To update only likes or dislikes on an existing review, pass likes or dislikes along with the review_id. The endpoint will skip the rating update and return immediately after saving the like/dislike counts.

​
Request parameters

​
item_code
string
required
Medusa product ID. Resolved to the Website Item via medusa_id.
​
customer_id
string
required
Medusa customer ID. Used to identify existing reviews.
​
customer_name
string
Display name of the reviewer.
​
review
string
Review text body.
​
review_id
integer
External review ID from the Medusa storefront. Stored for reference.
​
rating
integer
default:"1"
Star rating from 1 to 5. Minimum value is 1 (values below 1 are clamped to 1). Stored internally as rating / 5.
​
date
string
Review date in YYYY-MM-DD format.
​
likes
integer
Number of likes on an existing review. When provided alongside review_id, only likes/dislikes are updated.
​
dislikes
integer
Number of dislikes on an existing review.

​
Response

Returns a plain string on success:
  • "Review added successfully" — a new review was created.
  • "Review updated successfully" — an existing review was updated.
Returns an error object on failure: 
{ "status": "error", "message": "Website Item not found" }

​
Example

curl --request POST \
  --url "https://erp.example.com/api/method/medusa_integration.api.add_review_to_website_item" \
  --header "Content-Type: application/json" \
  --data '{
    "item_code": "prod_01ABC",
    "customer_id": "cus_01HXYZ",
    "customer_name": "Ahmed Al Farsi",
    "review": "Excellent quality, very happy with this product.",
    "review_id": 42,
    "rating": 5,
    "date": "2024-03-15"
  }'

​
Fetch relevant items

POST Guest 
POST https://<erpnext-site>/api/method/medusa_integration.api.fetch_relevant_items
Returns a ranked list of recommended products for a product detail page. The results are assembled in priority order:
  1. Variant items — other Website Items sharing the same parent (custom_parent_website_item).
  2. Manually linked recommendations — items listed in the recommended_items child table of the product.
  3. Same-collection items — all other published products in the same item group and its descendants, sorted by total sales quantity (descending).
Duplicate products (by Medusa ID) and the source product itself are excluded.

​
Request body

​
product_id
string
required
Medusa product ID of the product being viewed.
​
item_group
string
required
Collection title (ERPNext Item Group name) of the product. Used to fetch same-collection items.
​
cus_id
string
Medusa customer ID. Used to set is_wishlisted on each returned item.

​
Response

Returns an array of product objects. The source product (product_id) is excluded from the results.
​
product_id
string
Medusa product ID.
​
variant_id
string
Medusa variant ID.
​
title
string
Product display name.
​
item_code
string
ERPNext item code.
​
item_group
string
Item group name.
​
thumbnail
string | null
Absolute image URL.
​
rating
number
Overall rating (0–5).
​
is_wishlisted
integer
1 if wishlisted, 0 otherwise.
​
has_variants
boolean
Whether the item has child variants.
​
standard_price
number
Standard selling price (0 if hidden).
​
negotiated_price
number
Customer-specific price, or 0.

​
Example

curl --request POST \
  --url "https://erp.example.com/api/method/medusa_integration.api.fetch_relevant_items" \
  --header "Content-Type: application/json" \
  --data '{
    "product_id": "prod_01ABC",
    "item_group": "Instruments",
    "cus_id": "cus_01HXYZ"
  }'

​
Fetch relevant collection products

POST Guest 
POST https://<erpnext-site>/api/method/medusa_integration.api.fetch_relevant_collection_products
Returns the top-selling products for a given item group’s top-level category (Dental, Medical, Infection Control, or Medical Laboratory IVD). Products are pre-curated in the Product Collection singleton in ERPNext and sorted by sales count.
The Product Collection is refreshed by the add_top_selling_items_to_collection scheduled job. The contents reflect historical sales totals from submitted Sales Invoices.

​
Request body

​
item_group
string
required
ERPNext Item Group name. The endpoint walks up the group hierarchy to find the top-level category (Dental, Medical, Infection Control, or Medical Laboratory IVD) and returns products curated for that category.

​
Response fields

​
top_collection
string
The resolved top-level category name (e.g. "Dental").
​
products
object[]
Products sorted by sales count, descending.

​
Example

curl --request POST \
  --url "https://erp.example.com/api/method/medusa_integration.api.fetch_relevant_collection_products" \
  --header "Content-Type: application/json" \
  --data '{"item_group": "Instruments"}'

Build docs developers (and LLMs) love

Get started for freeTalk to us