Product Endpoints: Browse and Filter Storefront Items

These endpoints power the storefront product catalogue. They return paginated product listings with prices and filter metadata, individual variant data, product images and stock levels, specification breakdowns, and brand listings. All endpoints are guest-accessible and require no authentication.

Get website items

GET / POST Guest

POST https://<erpnext-site>/api/method/medusa_integration.api.get_website_items

Returns a paginated list of published Website Items for a given URL path. Prices are resolved against the customer’s price list when a customer_id is provided. Supports filtering by collection, brand, availability, and product specifications.

Request body

url

string

required

The current URL path (e.g. /products/dental). Used to resolve the matching ERPNext Item Group.

customer_id

string

Medusa customer ID. When provided, negotiated prices from the customer’s default price list are included in the response.

page

integer

default:"1"

Page number. Each page contains 20 items.

collection_title

string | string[]

Filter by one or more item group names (collection titles).

brand

string | string[]

Filter by one or more brand names.

availability

boolean

When true, only returns items where custom_in_stock is set.

sort_order

string

default:"asc"

Sort order for results. Accepted values: "asc" (name ascending), "desc" (name descending), "default" (ranking descending).

colour

string | string[]

Filter by one or more colour specification values.

shape

string | string[]

Filter by one or more shape specification values.

shade

string | string[]

Filter by one or more shade specification values.

Response fields

product_count

integer

Total number of products matching the current filters.

total_pages

integer

Total number of pages at 20 items per page.

current_page

integer

The requested page number.

items_in_page

integer

Number of items returned in this page.

distinct_parent_item_groups

object[]

Immediate child item groups of the resolved item group.

Show properties

title

string

Item group name.

handle

string

URL-safe slug of the item group name.

distinct_collection_titles

object[]

All item groups within the resolved item group tree, with product counts.

Show properties

name

string

Item group name.

count

integer

Number of products in this group.

distinct_brands

object[]

All brands present in the filtered result set, with product counts.

Show properties

name

string

Brand name.

count

integer

Number of products with this brand.

distinct_colours

string[]

Unique colour values from product specifications in the filtered set.

distinct_shapes

string[]

Unique shape values from product specifications in the filtered set.

distinct_shades

string[]

Unique shade values from product specifications in the filtered set.

paginatedProducts

object[]

The products for the current page.

Show properties

string

Medusa product ID.

variant_id

string

Medusa variant ID.

item_code

string

ERPNext item code.

title

string

Product display name.

collection_title

string

Item group (collection) name.

thumbnail

string | null

Absolute URL to the product image.

rating

number

Overall rating (0–5).

is_wishlisted

integer

1 if the customer has wishlisted this item, 0 otherwise.

has_variants

boolean

Whether the item has child variants.

colour

string | null

Colour from product specifications.

shape

string | null

Shape from product specifications.

shade

string | null

Shade from product specifications.

standard_price

number

Standard selling price. Returns 0 if price exceeds the visibility threshold.

negotiated_price

number

Customer-specific negotiated price. Returns 0 if no negotiated price exists or price is hidden.

Example

curl --request POST \
  --url "https://erp.example.com/api/method/medusa_integration.api.get_website_items" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "/products/dental",
    "customer_id": "cus_01HXYZ",
    "page": 1,
    "sort_order": "asc"
  }'

Get website variants

GET Guest

GET https://<erpnext-site>/api/method/medusa_integration.api.get_website_variants

Returns all child variant Website Items linked to a parent product. Used on the product detail page to display available variants.

Request parameters

medusa_id

string

required

The Medusa product ID of the parent Website Item.

customer_id

string

Medusa customer ID. Used to determine is_wishlisted status for each variant.

Response fields

status

string

"success" if variants were found, "empty" if none exist.

Array of variant items.

Show properties

string

Medusa product ID of the variant.

variant_id

string

Medusa variant ID.

title

string

Variant display name.

collection_title

string

Item group name.

rating

number

Overall rating (0–5).

is_wishlisted

integer

1 if wishlisted by the customer, 0 otherwise.

colour

string | null

Colour specification value.

shape

string | null

Shape specification value.

shade

string | null

Shade specification value.

Example

curl "https://erp.example.com/api/method/medusa_integration.api.get_website_variants?medusa_id=prod_01ABC&customer_id=cus_01HXYZ"

Get website image

GET Guest

GET https://<erpnext-site>/api/method/medusa_integration.api.get_website_image

Returns the product image URL, brand image, current stock quantity, display price, and long description for a single product. If the Website Item is not found, the corresponding Medusa product is flagged for deletion.

Request parameters

medusa_id

string

required

The Medusa product ID.

customer_id

string

Medusa customer ID. Used to resolve the customer’s default price list.

Response fields

status

string

"success" if at least one image is available, "empty" if none, "error" on failure.

image

string | null

Absolute URL to the product’s website image.

brand_image

string | null

Absolute URL to the brand logo image.

qty

number

Total actual stock quantity across all company warehouses.

price

number

Standard selling price. Returns 0 if price exceeds the visibility threshold.

description

string | null

HTML long description of the product (web_long_description).

Example

curl "https://erp.example.com/api/method/medusa_integration.api.get_website_image?medusa_id=prod_01ABC&customer_id=cus_01HXYZ"

Get distinct specs

POST Guest

POST https://<erpnext-site>/api/method/medusa_integration.api.get_distinct_specs

Returns the distinct colour, shape, and shade specification values for a given set of Medusa product IDs. Also returns a map indicating which products have child variants.

Request body

medusa_ids

string[]

required

Array of Medusa product IDs to fetch specifications for.

Response fields

distinct_colours

string[]

Sorted list of unique colour values across all specified products.

distinct_shapes

string[]

Sorted list of unique shape values.

distinct_shades

string[]

Sorted list of unique shade values.

has_variants_map

object

Mapping of Medusa product ID to 1 (has variants) or 0 (no variants).

Example

curl --request POST \
  --url "https://erp.example.com/api/method/medusa_integration.api.get_distinct_specs" \
  --header "Content-Type: application/json" \
  --data '{"medusa_ids": ["prod_01ABC", "prod_02DEF"]}'

Get all brands

GET Guest

GET https://<erpnext-site>/api/method/medusa_integration.api.get_all_brands

Returns all brands with their logo images. When item_group is provided, only brands with products in that group (and its descendants) are returned. Also includes the four top-level product categories.

Request parameters

item_group

string

ERPNext Item Group name. When provided, restricts brands to those with published Website Items in this group and its descendants.

Response fields

top_categories

string[]

Fixed list of top-level product categories: ["DENTAL", "MEDICAL", "Medical Laboratory IVD", "Infection Control"].

brand_list

object[]

All matching brands with images.

Show properties

brand

string

Brand name.

image

string | null

Absolute URL to the brand logo, or null if no image is attached.

Example

curl "https://erp.example.com/api/method/medusa_integration.api.get_all_brands?item_group=Dental"

Store Endpoints

Admin Utilities

Product Endpoints: Browse and Filter Storefront Items

Get website items

Request body

Response fields

Example

Get website variants

Request parameters

Response fields

Example

Get website image

Request parameters

Response fields

Example

Get distinct specs

Request body

Response fields

Example

Get all brands

Request parameters

Response fields

Example

Build docs developers (and LLMs) love

Store Endpoints

Admin Utilities

Documentation Index

​Get website items

​Request body

​Response fields

​Example

​Get website variants

​Request parameters

​Response fields

​Example

​Get website image

​Request parameters

​Response fields

​Example

​Get distinct specs

​Request body

​Response fields

​Example

​Get all brands

​Request parameters

​Response fields

​Example

Build docs developers (and LLMs) love

Get website items

Request body

Response fields

Example

Get website variants

Request parameters

Response fields

Example

Get website image

Request parameters

Response fields

Example

Get distinct specs

Request body

Response fields

Example

Get all brands

Request parameters

Response fields

Example