Skip to main content

​
Get Parent Categories

Retrieves all top-level (parent) categories.

​
Query Parameters

​
withCaching
boolean
default:"true"
Enable caching for faster response

​
Response

​
categories
array
Array of parent category objects

​
Response Codes

  • 200 OK - Categories retrieved successfully

​
Example

cURL
curl -X GET "https://your-server.com/api/categories/parent"

​
Success Response

[
  {
    "id": "parent-1",
    "name": "Electronics",
    "iconUrl": "https://cdn.example.com/icons/electronics.svg",
    "childCount": 5
  },
  {
    "id": "parent-2",
    "name": "Clothing",
    "iconUrl": "https://cdn.example.com/icons/clothing.svg",
    "childCount": 8
  }
]

​
Get Child Categories by Parent

Retrieves all child categories under a specific parent category.

​
Path Parameters

​
parentId
string (uuid)
required
Parent category identifier

​
Query Parameters

​
withCaching
boolean
default:"true"
Enable caching for faster response

​
Response

​
categories
array
Array of child category objects

​
Response Codes

  • 200 OK - Categories retrieved
  • 404 Not Found - Parent category not found

​
Example

cURL
curl -X GET "https://your-server.com/api/categories/child/parent-1"

​
Success Response

[
  {
    "id": "child-1",
    "name": "Smartphones",
    "parentId": "parent-1",
    "parentName": "Electronics",
    "imageUrl": "https://cdn.example.com/categories/smartphones.jpg",
    "productCount": 234
  },
  {
    "id": "child-2",
    "name": "Laptops",
    "parentId": "parent-1",
    "parentName": "Electronics",
    "imageUrl": "https://cdn.example.com/categories/laptops.jpg",
    "productCount": 156
  }
]

​
Get All Child Categories

Retrieves all child categories across all parent categories.

​
Response

​
categories
array
Array of all child category objects

​
Example

cURL
curl -X GET "https://your-server.com/api/categories/child"

​
Get Category Attributes (Seller)

Retrieves all attributes defined for a specific category. Sellers use this when creating products.

​
Path Parameters

​
childId
string (uuid)
required
Child category identifier

​
Response

​
attributes
array
Array of category attribute definitions

​
Response Codes

  • 200 OK - Attributes retrieved
  • 404 Not Found - Category not found

​
Example

cURL
curl -X GET "https://your-server.com/api/categories/child/child-1/attributes" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Success Response

[
  {
    "id": "attr-1",
    "name": "Brand",
    "type": "string",
    "required": true
  },
  {
    "id": "attr-2",
    "name": "Color",
    "type": "string",
    "required": true
  },
  {
    "id": "attr-3",
    "name": "Storage",
    "type": "string",
    "required": false
  }
]

​
Get Category Attributes with Values

Retrieves category attributes along with all unique values currently used by products. Useful for building filter UI.

​
Path Parameters

​
childId
string (uuid)
required
Child category identifier

​
Response

​
attributes
array
Array of attributes with their unique values

​
Response Codes

  • 200 OK - Data retrieved
  • 400 Bad Request - Invalid category ID
  • 404 Not Found - Category not found

​
Example

cURL
curl -X GET "https://your-server.com/api/categories/child/child-1/attributes-with-values"

​
Success Response

[
  {
    "attributeName": "Brand",
    "values": ["Apple", "Samsung", "Google", "OnePlus"]
  },
  {
    "attributeName": "Color",
    "values": ["Black", "White", "Blue", "Red"]
  },
  {
    "attributeName": "Storage",
    "values": ["64GB", "128GB", "256GB", "512GB"]
  }
]

​
Add Parent Category (Admin)

Creates a new parent category.

​
Request Body (multipart/form-data)

​
name
string
required
Category name
​
icon
file
required
Category icon image

​
Response Codes

  • 204 No Content - Category created
  • 400 Bad Request - Invalid data
  • 409 Conflict - Category name already exists

​
Example

cURL
curl -X POST "https://your-server.com/api/categories" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "name=Sports & Outdoors" \
  -F "icon=@/path/to/icon.svg"

​
Add Child Category (Admin)

Creates a new child category under a parent category.

​
Path Parameters

​
parentId
string (uuid)
required
Parent category identifier

​
Request Body (multipart/form-data)

​
name
string
required
Child category name
​
image
file
required
Category image

​
Response Codes

  • 204 No Content - Child category created
  • 400 Bad Request - Invalid data
  • 404 Not Found - Parent category not found
  • 409 Conflict - Child category name already exists under this parent

​
Example

cURL
curl -X POST "https://your-server.com/api/categories/parent-1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "name=Smartwatches" \
  -F "image=@/path/to/category-image.jpg"

​
Update Parent Category (Admin)

Updates a parent category.

​
Path Parameters

​
categoryId
string (uuid)
required
Category identifier

​
Request Body

​
name
string
New category name (optional)

​
Response Codes

  • 200 OK - Category updated, returns updated category object
  • 400 Bad Request - Invalid data
  • 404 Not Found - Category not found
  • 409 Conflict - Name already exists

​
Delete Category (Admin)

Deletes a category (parent or child).

​
Path Parameters

​
categoryId
string (uuid)
required
Category identifier

​
Response Codes

  • 204 No Content - Category deleted
  • 404 Not Found - Category not found

​
Example

cURL
curl -X DELETE "https://your-server.com/api/categories/category-id" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Deleting a parent category will also delete all its child categories and may affect existing products.

​
Add Category Attribute (Admin)

Adds a new attribute to a child category.

​
Path Parameters

​
childCategoryId
string (uuid)
required
Child category identifier

​
Request Body

​
name
string
required
Attribute name (e.g., “Screen Size”, “RAM”)
​
required
boolean
required
Whether this attribute is required for products in this category

​
Response Codes

  • 204 No Content - Attribute added
  • 400 Bad Request - Invalid data
  • 404 Not Found - Category not found
  • 409 Conflict - Attribute already exists

​
Delete Category Attribute (Admin)

Removes an attribute from a category.

​
Path Parameters

​
childCategoryId
string (uuid)
required
Child category identifier
​
attributeId
string (uuid)
required
Attribute identifier

​
Response Codes

  • 204 No Content - Attribute deleted
  • 404 Not Found - Category or attribute not found

Build docs developers (and LLMs) love

Get started for freeTalk to us