Appearance

list-categories ​

Method: GET
Path: /catalog/categories

Tags: Catalog

Summary ​

List all categories

Description ​

Returns a list of your product categories. The categories are returned sorted by creation date, with the most recently created categories appearing first.

Storefront SDK Usage ​

SDK Method: sdk.catalog.listCategories()

Example:

typescript
// Basic category listing
const { data, error } = await sdk.catalog.listCategories();

if (error) {
  console.error("Failed to list categories:", error);
  return;
}

console.log("Categories found:", data.categories?.length || 0);

data.categories?.forEach(category => {
  console.log(`Category: ${category.name} - ${category.description}`);
});

// With pagination
const { data: catData, error: catError } = await sdk.catalog.listCategories({
  page: 1,
  limit: 10
});

TypeScript Definition ​

typescript
"list-categories": {
        parameters: {
            query?: {
                /** @description search keyword */
                search?: components["parameters"]["searchKeyword"];
                /** @description JSON string format: {"field1":"asc", "field2":"desc"} */
                sort_by?: components["parameters"]["sortingParam"];
                /** @description return child categories up to nesting level */
                nested_level?: number;
                /** @description To return child categories using category id. */
                parent_category_id?: string;
                /** @description To return child categories using category slug */
                parent_category_slug?: string;
            };
            header?: never;
            path?: never;
            cookie?: never;
        };
        requestBody?: never;
        responses: {
            /** @description OK */
            200: {
                headers: {
                    [name: string]: unknown;
                };
                content: {
                    "application/json": {
                        /** @example all categories */
                        message: string;
                        success: boolean;
                        content: {
                            categories: components["schemas"]["ProductCategory"][];
                            pagination: components["schemas"]["Pagination"];
                        };
                    };
                };
            };
            400: components["responses"]["BadRequest"];
            401: components["responses"]["Unauthorized"];
            404: components["responses"]["NotFound"];
        };
    };

Component References ​

ReferenceResolves To
components["parameters"]["searchKeyword"]searchKeyword
components["parameters"]["sortingParam"]sortingParam
components["schemas"]["ProductCategory"]ProductCategory
components["schemas"]["Pagination"]Pagination
components["responses"]["BadRequest"]BadRequest
components["responses"]["Unauthorized"]Unauthorized
components["responses"]["NotFound"]NotFound

Parameters ​

  • search (query): search keyword
  • sort_by (query): JSON string format: {"field1":"asc", "field2":"desc"}
  • nested_level (query): return child categories up to nesting level
  • parent_category_id (query): To return child categories using category id.
  • parent_category_slug (query): To return child categories using category slug

Responses ​

200 ​

OK

400 ​

Bad request

401 ​

Not authorized for given operation on the Resource

404 ​

Requested resource not found

OpenAPI Definition ​

json
{
  "tags": [
    "Catalog"
  ],
  "operationId": "list-categories",
  "summary": "List all categories",
  "description": "Returns a list of your product categories. The categories are returned sorted by creation date, with the most recently created categories appearing first.",
  "externalDocs": {
    "url": "https://llm-docs.commercengine.io/storefront/operations/list-categories",
    "description": "API reference for the list-categories operation"
  },
  "parameters": [
    {
      "$ref": "#/components/parameters/searchKeyword"
    },
    {
      "$ref": "#/components/parameters/sortingParam"
    },
    {
      "name": "nested_level",
      "in": "query",
      "description": "return child categories up to nesting level",
      "schema": {
        "type": "integer",
        "default": 0,
        "maximum": 4,
        "minimum": 0
      }
    },
    {
      "name": "parent_category_id",
      "in": "query",
      "description": "To return child categories using category id.",
      "schema": {
        "type": "string",
        "example": "01JWZW41Y3FBKTZSP399SKANY7",
        "examples": [
          "01JWZW41Y3FBKTZSP399SKANY7"
        ]
      }
    },
    {
      "name": "parent_category_slug",
      "in": "query",
      "description": "To return child categories using category slug",
      "schema": {
        "type": "string",
        "example": "vitals"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "OK",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "message",
              "success",
              "content"
            ],
            "properties": {
              "message": {
                "type": "string",
                "examples": [
                  "all categories"
                ]
              },
              "success": {
                "type": "boolean"
              },
              "content": {
                "properties": {
                  "categories": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ProductCategory"
                    }
                  },
                  "pagination": {
                    "$ref": "#/components/schemas/Pagination"
                  }
                },
                "required": [
                  "categories",
                  "pagination"
                ],
                "type": "object"
              }
            }
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/BadRequest"
    },
    "401": {
      "$ref": "#/components/responses/Unauthorized"
    },
    "404": {
      "$ref": "#/components/responses/NotFound"
    }
  },
  "security": [
    {
      "Authorization": []
    }
  ],
  "x-speakeasy-group": "catalog",
  "x-speakeasy-ignore": false,
  "x-speakeasy-name-override": "listCategories"
}

Auto-generated from OpenAPI spec and TypeScript definitions

Last updated: