ProductsResource

This class is used to send requests to Store Product API Routes. All its method are available in the JS Client under the medusa.products property.

Products are saleable items in a store. This also includes saleable gift cards in a store. Using the methods in this class, you can filter products by categories, collections, sales channels, and more.

Related Guide: How to show products in a storefront.

Properties

variantsProductVariantsResourceRequired

An instance of ProductVariantsResource used to send requests to Store Product Variant API Routes.

---

Methods

list

Retrieves a list of products. The products can be filtered by fields such as id or q passed in the query parameter. The products can also be sorted or paginated. This method 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.

Example

To list products:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.products.list()
.then(({ products, limit, offset, count }) => {
  console.log(products.length);
})

To specify relations that should be retrieved within the products:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.products.list({
  expand: "variants"
})
.then(({ products, limit, offset, count }) => {
  console.log(products.length);
})

By default, only the first 100 records are retrieved. You can control pagination by specifying the limit and offset properties:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.products.list({
  expand: "variants",
  limit,
  offset
})
.then(({ products, limit, offset, count }) => {
  console.log(products.length);
})

Parameters

queryStoreGetProductsParams

Filters and pagination configurations to apply on the retrieved products.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<StoreProductsListRes>Required

Resolves to the list of products with pagination fields.

---

retrieve

Retrieve a Product's details. For accurate and correct pricing of the product 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 current sales channel. You can alternatively use a publishable API key in the request header instead of passing a sales_channel_id.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.products.retrieve(productId)
.then(({ product }) => {
  console.log(product.id);
})

Parameters

idstringRequired

The product's ID.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<StoreProductsRes>Required

Resolves to the product's details.

---

search

Run a search query on products using the search service installed on the Medusa backend. The searching is handled through the search service, so the returned data's format depends on the search service you're using.

Example

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.products.search({
  q: "Shirt"
})
.then(({ hits }) => {
  console.log(hits.length);
})

Parameters

searchOptionsStorePostSearchReqRequired

Fields to search products.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<StorePostSearchRes>Required

Resolves to the list of search results. The format of the items depends on the search engine installed on the Medusa backend.