# listProductCategories - Product Module Reference

This documentation provides a reference to the `listProductCategories` method. This belongs to the Product Module.

You should only use this methods when implementing complex customizations. For common cases, check out [available workflows instead](https://docs.medusajs.com/medusa-workflows-reference).

This method is used to retrieve a paginated list of product categories based on optional filters and configuration.

## Example

To retrieve a list of product categories using their IDs:

```ts
const categories = await productModuleService.listProductCategories({
  id: ["pcat_123", "pcat_321"],
})
```

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

:::note

You can only retrieve data models defined in the same module. To retrieve linked data models
from other modules, use [Query](https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.

:::

```ts
const categories = await productModuleService.listProductCategories(
  {
    id: ["pcat_123", "pcat_321"],
  },
  {
    relations: ["products"],
  }
)
```

By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter:

```ts
const categories = await productModuleService.listProductCategories(
  {
    id: ["pcat_123", "pcat_321"],
  },
  {
    relations: ["products"],
    take: 20,
    skip: 2,
  }
)
```

## Parameters

- filters: (\[FilterableProductCategoryProps]\(../../../interfaces/product.FilterableProductCategoryProps/page.mdx)) The filters to be applied on the retrieved product categories.

  - $and: ((\[FilterableProductCategoryProps]\(../../../interfaces/product.FilterableProductCategoryProps/page.mdx) \\| \[BaseFilterable]\(../../../interfaces/product.BaseFilterable/page.mdx)\&#60;\[FilterableProductCategoryProps]\(../../../interfaces/product.FilterableProductCategoryProps/page.mdx)\&#62;)\[]) An array of filters to apply on the entity, where each item in the array is joined with an "and" condition.

    - $and: ((\[FilterableProductCategoryProps]\(../../../interfaces/product.FilterableProductCategoryProps/page.mdx) \\| \[BaseFilterable]\(../../../interfaces/product.BaseFilterable/page.mdx)\&#60;\[FilterableProductCategoryProps]\(../../../interfaces/product.FilterableProductCategoryProps/page.mdx)\&#62;)\[]) An array of filters to apply on the entity, where each item in the array is joined with an "and" condition.

    - $or: ((\[FilterableProductCategoryProps]\(../../../interfaces/product.FilterableProductCategoryProps/page.mdx) \\| \[BaseFilterable]\(../../../interfaces/product.BaseFilterable/page.mdx)\&#60;\[FilterableProductCategoryProps]\(../../../interfaces/product.FilterableProductCategoryProps/page.mdx)\&#62;)\[]) An array of filters to apply on the entity, where each item in the array is joined with an "or" condition.

    - q: (\`string\`) Filter product categories based on searchable fields

    - id: (\`string\` \\| \`string\`\[]) The IDs to filter product categories by.

    - name: (\`string\` \\| \`string\`\[]) The names to filter product categories by.

    - parent\_category\_id: (\`null\` \\| \`string\` \\| \`string\`\[]) Filter product categories by their parent category's ID.

    - handle: (\`string\` \\| \`string\`\[]) The handles to filter product categories by.

    - is\_active: (\`boolean\`) Filter product categories by whether they're active.

    - is\_internal: (\`boolean\`) Filter product categories by whether they're internal.

    - include\_descendants\_tree: (\`boolean\`) Whether to include children of retrieved product categories.

    - include\_ancestors\_tree: (\`boolean\`) Whether to include parents of retrieved product categories.

  - $or: ((\[FilterableProductCategoryProps]\(../../../interfaces/product.FilterableProductCategoryProps/page.mdx) \\| \[BaseFilterable]\(../../../interfaces/product.BaseFilterable/page.mdx)\&#60;\[FilterableProductCategoryProps]\(../../../interfaces/product.FilterableProductCategoryProps/page.mdx)\&#62;)\[]) An array of filters to apply on the entity, where each item in the array is joined with an "or" condition.

    - $and: ((\[FilterableProductCategoryProps]\(../../../interfaces/product.FilterableProductCategoryProps/page.mdx) \\| \[BaseFilterable]\(../../../interfaces/product.BaseFilterable/page.mdx)\&#60;\[FilterableProductCategoryProps]\(../../../interfaces/product.FilterableProductCategoryProps/page.mdx)\&#62;)\[]) An array of filters to apply on the entity, where each item in the array is joined with an "and" condition.

    - $or: ((\[FilterableProductCategoryProps]\(../../../interfaces/product.FilterableProductCategoryProps/page.mdx) \\| \[BaseFilterable]\(../../../interfaces/product.BaseFilterable/page.mdx)\&#60;\[FilterableProductCategoryProps]\(../../../interfaces/product.FilterableProductCategoryProps/page.mdx)\&#62;)\[]) An array of filters to apply on the entity, where each item in the array is joined with an "or" condition.

    - q: (\`string\`) Filter product categories based on searchable fields

    - id: (\`string\` \\| \`string\`\[]) The IDs to filter product categories by.

    - name: (\`string\` \\| \`string\`\[]) The names to filter product categories by.

    - parent\_category\_id: (\`null\` \\| \`string\` \\| \`string\`\[]) Filter product categories by their parent category's ID.

    - handle: (\`string\` \\| \`string\`\[]) The handles to filter product categories by.

    - is\_active: (\`boolean\`) Filter product categories by whether they're active.

    - is\_internal: (\`boolean\`) Filter product categories by whether they're internal.

    - include\_descendants\_tree: (\`boolean\`) Whether to include children of retrieved product categories.

    - include\_ancestors\_tree: (\`boolean\`) Whether to include parents of retrieved product categories.

  - q: (\`string\`) Filter product categories based on searchable fields

  - id: (\`string\` \\| \`string\`\[]) The IDs to filter product categories by.

  - name: (\`string\` \\| \`string\`\[]) The names to filter product categories by.

  - parent\_category\_id: (\`null\` \\| \`string\` \\| \`string\`\[]) Filter product categories by their parent category's ID.

  - handle: (\`string\` \\| \`string\`\[]) The handles to filter product categories by.

  - is\_active: (\`boolean\`) Filter product categories by whether they're active.

  - is\_internal: (\`boolean\`) Filter product categories by whether they're internal.

  - include\_descendants\_tree: (\`boolean\`) Whether to include children of retrieved product categories.

  - include\_ancestors\_tree: (\`boolean\`) Whether to include parents of retrieved product categories.
- config: (\[FindConfig]\(../../../interfaces/product.FindConfig/page.mdx)\&#60;\[ProductCategoryDTO]\(../../../interfaces/product.ProductCategoryDTO/page.mdx)\&#62;) The configurations determining how the product categories are retrieved. Its properties, such as \`select\` or \`relations\`, accept the
  attributes or relations associated with a product category.

  - select: ((\`string\` & \`object\` \\| keyof Entity)\[]) An array of strings, each being attribute names of the entity to retrieve in the result.

  - skip: (\`null\` \\| \`number\`) A number indicating the number of records to skip before retrieving the results.

  - take: (\`null\` \\| \`number\`) A number indicating the number of records to return in the result.

  - relations: (\`string\`\[]) An array of strings, each being relation names of the entity to retrieve in the result.

    You can only retrieve data models defined in the same module. To retrieve linked data models
    from other modules, use \[Query]\(https://docs.medusajs.com/learn/fundamentals/module-links/query) instead.

  - order: (\[FindConfigOrder]\(../../../types/product.FindConfigOrder/page.mdx)) An object used to specify how to sort the returned records. Its keys are the names of attributes of the entity, and a key's value can either be \`ASC\`
    to sort retrieved records in an ascending order, or \`DESC\` to sort retrieved records in a descending order.

  - withDeleted: (\`boolean\`) A boolean indicating whether deleted records should also be retrieved as part of the result. This only works if the entity extends the
    \`SoftDeletableEntity\` class.

  - filters: (\`Record\<string, any>\`) Enable ORM specific defined filters

  - options: (\`Record\<string, any>\`) Enable ORM specific defined options
- sharedContext: (\[Context]\(../../../interfaces/product.Context/page.mdx)) A context used to share resources, such as transaction manager, between the application and the module.

  - transactionManager: (TManager) An instance of a transaction manager of type \`TManager\`, which is a typed parameter passed to the context to specify the type of the \`transactionManager\`.

  - manager: (TManager) An instance of a manager, typically an entity manager, of type \`TManager\`, which is a typed parameter passed to the context to specify the type of the \`manager\`.

  - isolationLevel: (\`string\`) A string indicating the isolation level of the context. Possible values are \`READ UNCOMMITTED\`, \`READ COMMITTED\`, \`REPEATABLE READ\`, or \`SERIALIZABLE\`.

  - enableNestedTransactions: (\`boolean\`) A boolean value indicating whether nested transactions are enabled.

  - eventGroupId: (\`string\`) A string indicating the ID of the group to aggregate the events to be emitted at a later point.

  - transactionId: (\`string\`) A string indicating the ID of the current transaction.

  - messageAggregator: (\[IMessageAggregator]\(../../../interfaces/product.IMessageAggregator/page.mdx)) An instance of a message aggregator, which is used to aggregate messages to be emitted at a later point.

  - requestId: (\`string\`) A string indicating the ID of the current request.

  - idempotencyKey: (\`string\`) A string indicating the idempotencyKey of the current workflow execution.

  - parentStepIdempotencyKey: (\`string\`) A string indicating the idempotencyKey of the parent workflow execution.

  - preventReleaseEvents: (\`boolean\`) preventReleaseEvents

  - isCancelling: (\`boolean\`) A boolean value indicating whether the current workflow execution is being cancelled.

## Returns

- Promise: (Promise\&#60;\[ProductCategoryDTO]\(../../../interfaces/product.ProductCategoryDTO/page.mdx)\[]\&#62;) The list of product categories.

  - ProductCategoryDTO\[]: (\[ProductCategoryDTO]\(../../../interfaces/product.ProductCategoryDTO/page.mdx)\[])

    - id: (\`string\`) The ID of the product category.

    - name: (\`string\`) The name of the product category.

    - description: (\`string\`) The description of the product category.

    - handle: (\`string\`) The handle of the product category. The handle can be used to create slug URL paths.

    - is\_active: (\`boolean\`) Whether the product category is active.

    - is\_internal: (\`boolean\`) Whether the product category is internal. This can be used to only show the product category to admins and hide it from customers.

    - rank: (\`number\`) The ranking of the product category among sibling categories.

    - parent\_category: (\`null\` \\| \[ProductCategoryDTO]\(../../../interfaces/product.ProductCategoryDTO/page.mdx)) The associated parent category.

      - id: (\`string\`) The ID of the product category.

      - name: (\`string\`) The name of the product category.

      - description: (\`string\`) The description of the product category.

      - handle: (\`string\`) The handle of the product category. The handle can be used to create slug URL paths.

      - is\_active: (\`boolean\`) Whether the product category is active.

      - is\_internal: (\`boolean\`) Whether the product category is internal. This can be used to only show the product category to admins and hide it from customers.

      - rank: (\`number\`) The ranking of the product category among sibling categories.

      - parent\_category: (\`null\` \\| \[ProductCategoryDTO]\(../../../interfaces/product.ProductCategoryDTO/page.mdx)) The associated parent category.

      - parent\_category\_id: (\`null\` \\| \`string\`) The associated parent category id.

      - category\_children: (\[ProductCategoryDTO]\(../../../interfaces/product.ProductCategoryDTO/page.mdx)\[]) The associated child categories.

      - products: (\[ProductDTO]\(../../../interfaces/product.ProductDTO/page.mdx)\[]) The associated products.

      - created\_at: (\`string\` \\| \`Date\`) When the product category was created.

      - updated\_at: (\`string\` \\| \`Date\`) When the product category was updated.

      - metadata: (\[MetadataType]\(../../../types/product.MetadataType/page.mdx)) The ranking of the product category among sibling categories.

      - deleted\_at: (\`string\` \\| \`Date\`) When the product category was deleted.

    - parent\_category\_id: (\`null\` \\| \`string\`) The associated parent category id.

    - category\_children: (\[ProductCategoryDTO]\(../../../interfaces/product.ProductCategoryDTO/page.mdx)\[]) The associated child categories.

      - id: (\`string\`) The ID of the product category.

      - name: (\`string\`) The name of the product category.

      - description: (\`string\`) The description of the product category.

      - handle: (\`string\`) The handle of the product category. The handle can be used to create slug URL paths.

      - is\_active: (\`boolean\`) Whether the product category is active.

      - is\_internal: (\`boolean\`) Whether the product category is internal. This can be used to only show the product category to admins and hide it from customers.

      - rank: (\`number\`) The ranking of the product category among sibling categories.

      - parent\_category: (\`null\` \\| \[ProductCategoryDTO]\(../../../interfaces/product.ProductCategoryDTO/page.mdx)) The associated parent category.

      - parent\_category\_id: (\`null\` \\| \`string\`) The associated parent category id.

      - category\_children: (\[ProductCategoryDTO]\(../../../interfaces/product.ProductCategoryDTO/page.mdx)\[]) The associated child categories.

      - products: (\[ProductDTO]\(../../../interfaces/product.ProductDTO/page.mdx)\[]) The associated products.

      - created\_at: (\`string\` \\| \`Date\`) When the product category was created.

      - updated\_at: (\`string\` \\| \`Date\`) When the product category was updated.

      - metadata: (\[MetadataType]\(../../../types/product.MetadataType/page.mdx)) The ranking of the product category among sibling categories.

      - deleted\_at: (\`string\` \\| \`Date\`) When the product category was deleted.

    - products: (\[ProductDTO]\(../../../interfaces/product.ProductDTO/page.mdx)\[]) The associated products.

      - id: (\`string\`) The ID of the product.

      - title: (\`string\`) The title of the product.

      - handle: (\`string\`) The handle of the product. The handle can be used to create slug URL paths.

      - subtitle: (\`null\` \\| \`string\`) The subttle of the product.

      - description: (\`null\` \\| \`string\`) The description of the product.

      - is\_giftcard: (\`boolean\`) Whether the product is a gift card.

      - status: (\[ProductStatus]\(../../../types/product.ProductStatus/page.mdx)) The status of the product.

      - thumbnail: (\`null\` \\| \`string\`) The URL of the product's thumbnail.

      - width: (\`null\` \\| \`number\`) The width of the product.

      - weight: (\`null\` \\| \`number\`) The weight of the product.

      - length: (\`null\` \\| \`number\`) The length of the product.

      - height: (\`null\` \\| \`number\`) The height of the product.

      - origin\_country: (\`null\` \\| \`string\`) The origin country of the product.

      - hs\_code: (\`null\` \\| \`string\`) The HS Code of the product.

      - mid\_code: (\`null\` \\| \`string\`) The MID Code of the product.

      - material: (\`null\` \\| \`string\`) The material of the product.

      - collection: (\`null\` \\| \[ProductCollectionDTO]\(../../../interfaces/product.ProductCollectionDTO/page.mdx)) The associated product collection.

      - collection\_id: (\`null\` \\| \`string\`) The associated product collection id.

      - type: (\`null\` \\| \[ProductTypeDTO]\(../../../interfaces/product.ProductTypeDTO/page.mdx)) The associated product type.

      - type\_id: (\`null\` \\| \`string\`) The associated product type id.

      - tags: (\[ProductTagDTO]\(../../../interfaces/product.ProductTagDTO/page.mdx)\[]) The associated product tags.

      - variants: (\[ProductVariantDTO]\(../../../interfaces/product.ProductVariantDTO/page.mdx)\[]) The associated product variants.

      - options: (\[ProductOptionDTO]\(../../../interfaces/product.ProductOptionDTO/page.mdx)\[]) The associated product options.

      - images: (\[ProductImageDTO]\(../../../interfaces/product.ProductImageDTO/page.mdx)\[]) The associated product images.

      - external\_id: (\`null\` \\| \`string\`) The ID of the product in an external system. This is useful if you're integrating the product with a third-party service and want to maintain
        a reference to the ID in the integrated service.

      - created\_at: (\`string\` \\| \`Date\`) When the product was created.

      - updated\_at: (\`string\` \\| \`Date\`) When the product was updated.

      - deleted\_at: (\`string\` \\| \`Date\`) When the product was deleted.

      - categories: (\`null\` \\| \[ProductCategoryDTO]\(../../../interfaces/product.ProductCategoryDTO/page.mdx)\[]) The associated product categories.

      - discountable: (\`boolean\`) Whether the product can be discounted.

      - metadata: (\[MetadataType]\(../../../types/product.MetadataType/page.mdx)) Holds custom data in key-value pairs.

    - created\_at: (\`string\` \\| \`Date\`) When the product category was created.

    - updated\_at: (\`string\` \\| \`Date\`) When the product category was updated.

    - metadata: (\[MetadataType]\(../../../types/product.MetadataType/page.mdx)) The ranking of the product category among sibling categories.

    - deleted\_at: (\`string\` \\| \`Date\`) When the product category was deleted.
