Categories API

Manage your product categories with support for nested hierarchies.

Endpoints

GET

/categories

categories:read

Retrieve a flat list of all categories.

GET

/categories/tree

categories:read

Retrieve the full category tree with nested children.

GET

/categories/:id

categories:read

Retrieve a single category by its ID.

POST

/categories

categories:write

Create a new category. Set parentId to create a subcategory.

PUT

/categories/:id

categories:write

Update an existing category. Partial updates are supported.

DELETE

/categories/:id

categories:write

Soft-delete a category. Products in this category will not be affected.

Field Reference

Field	Type	Required	Description
id	string	No	Unique category identifier (read-only)
name	string	Yes	Category name
slug	string	No	URL-friendly slug (auto-generated if omitted)
description	string	No	Category description
parentId	string	No	Parent category ID for nesting
imageUrl	string	No	Category image URL
sortOrder	integer	No	Display sort order (lower = first)
isActive	boolean	No	Whether the category is active (default: true)
children	Category[]	No	Nested child categories (only in tree endpoint)
createdAt	datetime	No	ISO 8601 timestamp (read-only)
updatedAt	datetime	No	ISO 8601 timestamp (read-only)

Example

Get category tree

bash

curl "https://api.mercozy.com/api/v1/external/categories/tree" \
  -H "X-API-Key: mk_live_xxxxx"

Create a category

bash

curl -X POST "https://api.mercozy.com/api/v1/external/categories" \
  -H "X-API-Key: mk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Electronics",
    "description": "Electronic devices and accessories",
    "sortOrder": 1,
    "isActive": true
  }'

Example Response (Tree)

json

{
  "data": [
    {
      "id": "cat_abc123",
      "name": "Electronics",
      "slug": "electronics",
      "description": "Electronic devices and accessories",
      "parentId": null,
      "imageUrl": null,
      "sortOrder": 1,
      "isActive": true,
      "children": [
        {
          "id": "cat_def456",
          "name": "Smartphones",
          "slug": "smartphones",
          "description": "Mobile phones",
          "parentId": "cat_abc123",
          "imageUrl": null,
          "sortOrder": 1,
          "isActive": true,
          "children": []
        }
      ],
      "createdAt": "2025-12-15T10:30:00Z",
      "updatedAt": "2025-12-15T10:30:00Z"
    }
  ]
}