Medusa
Store API
Admin API
Medusa
  • Getting Started
  • Auth
  • Carts
  • Customers
  • Gift Cards
  • Orders
  • Order Edits
  • Payment Collections
  • Products
    • Search ProductsPOST
    • List ProductsGET
    • Get a ProductGET
  • Product Variants
  • Product Tags
  • Product Categories
  • Product Collections
  • Product Types
  • Regions
  • Returns
  • Return Reasons
  • Shipping Options
  • Swaps
logoPowered by Apidog
  1. Products

List Products

GET/store/products

Retrieves a list of products. The products can be filtered by fields such as id or q. The products can also be sorted or paginated.
This API Route can also be used to retrieve a product by its handle.

For accurate and correct pricing of the products based on the customer's context, it's highly recommended to pass fields such as
region_id, currency_code, and cart_id when available.

Passing sales_channel_id ensures retrieving only products available in the specified sales channel.
You can alternatively use a publishable API key in the request header instead of passing a sales_channel_id.

Request

Query Params
q
string 
optional

term used to search products' title, description, variant's title, variant's sku, and collection's title.

id
string 
optional

Filter by IDs.

sales_channel_id
array[string]
optional

Filter by sales channel IDs. When provided, only products available in the selected sales channels are retrieved. Alternatively, you can pass a publishable API key in the request header and this will have the same effect.

collection_id
array[string]
optional

Filter by product collection IDs. When provided, only products that belong to the specified product collections are retrieved.

type_id
array[string]
optional

Filter by product type IDs. When provided, only products that belong to the specified product types are retrieved.

tags
array[string]
optional

Filter by product tag IDs. When provided, only products that belong to the specified product tags are retrieved.

title
string 
optional

Filter by title.

description
string 
optional

Filter by description

handle
string 
optional

Filter by handle.

is_giftcard
string 
optional

Whether to retrieve regular products or gift-card products.

lt
array[string]
optional

filter by dates less than this date

Example:
["",""]
gt
array[string]
optional

filter by dates greater than this date

Example:
["",""]
lte
array[string]
optional

filter by dates less than or equal to this date

Example:
["",""]
gte
array[string]
optional

filter by dates greater than or equal to this date

Example:
["",""]
category_id
array[string]
optional

Filter by product category IDs. When provided, only products that belong to the specified product categories are retrieved.

include_category_children
string 
optional

Whether to include child product categories when filtering using the category_id field.

offset
integer 
optional

The number of products to skip when retrieving the products.

limit
integer 
optional

Limit the number of products returned.

expand
string 
optional

Comma-separated relations that should be expanded in the returned products.

fields
string 
optional

Comma-separated fields that should be included in the returned products.

order
string 
optional

A product field to sort-order the retrieved products by.

cart_id
string 
optional

The ID of the cart. This is useful for accurate pricing based on the cart's context.

region_id
string 
optional

The ID of the region. This is useful for accurate pricing based on the selected region.

currency_code
string 
optional

A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency.

Request samples

Responses

OK(200)
Client Error or Multiple Errors(400)
Not Found Error(404)
Invalid State Error(409)
Invalid Request Error(422)
Server Error(500)
HTTP Code: 200
Content Type : JSONapplication/json
Data Schema
The list of products with pagination fields.
count
integer 
required

The total number of items available

offset
integer 
required

The number of products skipped when retrieving the products.

limit
integer 
required

The number of items per page

products
array[object (Priced Product) {35}] 
required

An array of products details.

id
string 
required

The product's ID

Example:
prod_01G1G5V2MBA328390B5AXJ610F
title
string 
required

A title that can be displayed for easy identification of the Product.

Example:
Medusa Coffee Mug
subtitle
string  | null 
required

An optional subtitle that can be used to further specify the Product.

description
string  | null 
required

A short description of the Product.

Example:
Every programmer's best friend.
handle
string  | null 
required

A unique identifier for the Product (e.g. for slug structure).

Example:
coffee-mug
is_giftcard
boolean 
required

Whether the Product represents a Gift Card. Products that represent Gift Cards will automatically generate a redeemable Gift Card code once they are purchased.

Default:
false
thumbnail
string <uri> | null 
required

A URL to an image file that can be used to identify the Product.

profile_id
string 
required

The ID of the shipping profile that the product belongs to. The shipping profile has a set of defined shipping options that can be used to fulfill the product.

Example:
sp_01G1G5V239ENSZ5MV4JAR737BM
weight
number  | null 
required

The weight of the Product Variant. May be used in shipping rate calculations.

Example:
null
length
number  | null 
required

The length of the Product Variant. May be used in shipping rate calculations.

Example:
null
height
number  | null 
required

The height of the Product Variant. May be used in shipping rate calculations.

Example:
null
width
number  | null 
required

The width of the Product Variant. May be used in shipping rate calculations.

Example:
null
hs_code
string  | null 
required

The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

Example:
null
origin_country
string  | null 
required

The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.

Example:
null
mid_code
string  | null 
required

The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.

Example:
null
material
string  | null 
required

The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.

Example:
null
collection_id
string  | null 
required

The ID of the product collection that the product belongs to.

Example:
pcol_01F0YESBFAZ0DV6V831JXWH0BG
type_id
string  | null 
required

The ID of the product type that the product belongs to.

Example:
ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
discountable
boolean 
required

Whether the Product can be discounted. Discounts will not apply to Line Items of this Product when this flag is set to false.

Default:
true
external_id
string  | null 
required

The external ID of the product

Example:
null
created_at
string <date-time>
required

The date with timezone at which the resource was created.

updated_at
string <date-time>
required

The date with timezone at which the resource was updated.

deleted_at
string <date-time> | null 
required

The date with timezone at which the resource was deleted.

status
enum<string> 
required

The status of the product

Allowed values:
draftproposedpublishedrejected
Default:
draft
metadata
object  | null 
required

An optional key-value map with additional details

Example:
{"car":"white"}
categories
array[object (Product Category) {15}] 
optional

The details of the product categories that this product belongs to.

profile
object 
Shipping Profile
optional

A Shipping Profile has a set of defined Shipping Options that can be used to fulfill a given set of Products. For example, gift cards are shipped differently than physical products, so a shipping profile with the type gift_card groups together the shipping options that can only be used for gift cards.

profiles
array[object (Shipping Profile) {9}]  | null 
optional

Available if the relation profiles is expanded.

collection
object 
Product Collection
optional

A Product Collection allows grouping together products for promotional purposes. For example, an admin can create a Summer collection, add products to it, and showcase it on the storefront.

type
object 
Product Type
optional

A Product Type can be added to Products for filtering and reporting purposes.

tags
array[object (Product Tag) {6}] 
optional

The details of the product tags used in this product.

images
array[object (Image) {6}] 
optional

The details of the product's images.

options
array[object (Product Option) {9}] 
optional

The details of the Product Options that are defined for the Product. The product's variants will have a unique combination of values of the product's options.

sales_channels
array[object (Sales Channel) {9}] 
optional

The details of the sales channels this product is available in.

variants
array[object (Priced Product Variant) {35}] 
optional

The product variants and their prices.

Example
Not configured
Last modified: a year ago