ProductCategoriesResource

Note

To use this resource, make sure to enable its feature flag: product_categories

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

Products can be categoriezed into categories. A product can be associated more than one category. Using the methods in this class, you can list or retrieve a category's details and products.

Related Guide: How to use product categories in a storefront.

Methods

list

Retrieve a list of product categories. The product categories can be filtered by fields such as handle or q passed in the query parameter. The product categories can also be paginated. This method can also be used to retrieve a product category by its handle.

Example

To list product categories:

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

To retrieve a product category by its handle:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.productCategories.list({
  handle: "women",
})
.then(({ product_categories, limit, offset, count }) => {
  if (!product_categories.length) {
    // category does not exist
  }
  const category = product_categories[0]
})

To specify relations that should be retrieved within the product categories:

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

Parameters

queryStoreGetProductCategoriesParams

Filters and pagination configurations to apply on the retrieved product categories.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<StoreGetProductCategoriesRes>Required

Resolves to the list of product categories with pagination fields.

---

retrieve

Retrieve a Product Category's details.

Example

A simple example that retrieves a product category by its ID:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.productCategories.retrieve(productCategoryId)
.then(({ product_category }) => {
  console.log(product_category.id);
})

To specify relations that should be retrieved:

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.productCategories.retrieve(productCategoryId, {
  expand: "products"
})
.then(({ product_category }) => {
  console.log(product_category.id);
})

Parameters

idstringRequired

The ID of the product category.

queryStoreGetProductCategoriesCategoryParams

Configurations to apply on the retrieved product categories.

customHeadersRecord<string, any>Required

Custom headers to attach to the request.

Default: {}

Returns

ResponsePromiseResponsePromise<StoreGetProductCategoriesCategoryRes>Required

Resolves to the product category's details.