List Product Categories

Retrieve a list of product categories. The product categories can be filtered by fields such as handle or q. The product categories can also be paginated. This API Route can also be used to retrieve a product category by its handle.

Request

Query Params

string

optional

term used to search product category's names and handles.

handle

string

optional

Filter by handle.

parent_category_id

string

optional

Filter by the ID of a parent category. Only children of the provided parent category are retrieved.

include_descendants_tree

boolean

optional

Whether all nested categories inside a category should be retrieved.

offset

integer

optional

The number of product categories to skip when retrieving the product categories.

limit

integer

optional

Limit the number of product categories returned.

expand

string

optional

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

fields

string

optional

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

Responses

🟢200OK

application/json

Body

The list of product categories with pagination fields.

count

integer

required

The total number of items available

offset

integer

required

The number of product categories skipped when retrieving the product categories.

limit

integer

required

The number of items per page

product_categories

array[object (Product Category) {15}]

required

An array of product categories details.

string

required

The product category's ID

Example:

pcat_01G2SG30J8C85S4A5CHM2S1NS2

name

string

required

The product category's name

Example:

Regular Fit

description

string

optional

The product category's description.

Default:

handle

string

required

A unique string that identifies the Product Category - can for example be used in slug structures.

Example:

regular-fit

mpath

string | null

required

A string for Materialized Paths - used for finding ancestors and descendents

Example:

pcat_id1.pcat_id2.pcat_id3

is_internal

boolean

required

A flag to make product category an internal category for admins

Default:

false

is_active

boolean

required

A flag to make product category visible/hidden in the store front

Default:

false

rank

integer

optional

An integer that depicts the rank of category in a tree node

Default:

parent_category_id

string | null

required

The ID of the parent category.

Default:

null

parent_category

object | null

optional

The details of the parent of this category.

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.

category_children

array [object]

required

The details of the category's children.

products

array [object]

optional

The details of the products that belong to this category.

metadata

object | null

required

An optional key-value map with additional details

Example:

{"car":"white"}

Example

{
  "count": 0,
  "offset": 0,
  "limit": 0,
  "product_categories": [
    {
      "id": "pcat_01G2SG30J8C85S4A5CHM2S1NS2",
      "name": "Regular Fit",
      "description": "",
      "handle": "regular-fit",
      "mpath": "pcat_id1.pcat_id2.pcat_id3",
      "is_internal": false,
      "is_active": false,
      "rank": 0,
      "parent_category_id": null,
      "parent_category": {},
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "category_children": [
        {}
      ],
      "products": [
        {}
      ],
      "metadata": {
        "car": "white"
      }
    }
  ]
}

🟠400Client Error or Multiple Errors

🟠401User is not authorized. Must log in first

🟠404Not Found Error

🟠409Invalid State Error

🟠422Invalid Request Error

🔴500Server Error

List Product Categories

Request

Request samples

Responses