Shop Categories Management

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-09-23
Version: v1.0

Short Description: The Product Category Management API provides comprehensive functionality for managing hierarchical product categories within the NextGate platform. It supports creating, updating, retrieving, and managing parent-child category relationships with role-based access control.

Hints:

All endpoints require authentication except for read operations
Super Admin role required for create, update, delete, and activate operations
Categories support hierarchical structure (parent-child relationships)
Soft delete is implemented - categories are marked as inactive instead of permanent deletion
Category names must be unique across the system
Pagination is 1-indexed (page starts from 1)

Endpoints

1. Create Product Category

Purpose: Creates a new product category with optional parent category assignment

Endpoint: POST /api/v1/products/categories

Access Level: 🔒 Protected (Requires Super Admin role - currently commented out in code)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	application/json

Request JSON Sample:

{
  "categoryName": "Electronics",
  "categoryDescription": "All electronic products and accessories",
  "categoryIconUrl": "https://example.com/icons/electronics.png",
  "parentCategoryId": null
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
categoryName	string	Yes	Unique name for the category	Max: 100 characters, must be unique
categoryDescription	string	No	Description of the category	Max: 500 characters
categoryIconUrl	string	No	Valid URL for category icon	Valid URL format, Max: 1000 characters
parentCategoryId	UUID	No	ID of parent category for hierarchical structure	Must be existing category UUID

Response JSON Sample:

{
  "success": true,
  "message": "Product category created successfully",
  "data": {
    "categoryId": "123e4567-e89b-12d3-a456-426614174000",
    "categoryName": "Electronics",
    "categoryDescription": "All electronic products and accessories",
    "categoryIconUrl": "https://example.com/icons/electronics.png",
    "parentCategoryId": null,
    "parentCategoryName": null,
    "createdTime": "2025-09-23T10:30:00",
    "editedTime": "2025-09-23T10:30:00",
    "isActive": true,
    "createdBy": "456e7890-e89b-12d3-a456-426614174001",
    "editedBy": "456e7890-e89b-12d3-a456-426614174001"
  }
}

Response Fields:

Field	Description
categoryId	Unique identifier for the category
categoryName	Name of the category
categoryDescription	Description of the category
categoryIconUrl	URL of the category icon
parentCategoryId	ID of parent category (null if root category)
parentCategoryName	Name of parent category (null if root category)
createdTime	Timestamp when category was created
editedTime	Timestamp when category was last modified
isActive	Boolean indicating if category is active
createdBy	ID of user who created the category
editedBy	ID of user who last modified the category

Error Responses:

400 Bad Request: Invalid request data or validation errors
401 Unauthorized: Authentication required
403 Forbidden: Super Admin role required
404 Not Found: Parent category not found (when parentCategoryId provided)
409 Conflict: Category name already exists

2. Update Product Category

Purpose: Updates an existing product category by ID

Endpoint: PUT /api/v1/products/categories/{categoryId}

Access Level: 🔒 Protected (Requires Super Admin role)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	application/json

Path Parameters:

Parameter	Type	Required	Description	Validation
categoryId	UUID	Yes	ID of category to update	Valid UUID format

Request JSON Sample:

{
  "categoryName": "Updated Electronics",
  "categoryDescription": "Updated description for electronics category",
  "categoryIconUrl": "https://example.com/icons/electronics-updated.png",
  "parentCategoryId": "789e0123-e89b-12d3-a456-426614174002"
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
categoryName	string	Yes	Updated name for the category	Max: 100 characters, must be unique
categoryDescription	string	No	Updated description	Max: 500 characters
categoryIconUrl	string	No	Updated icon URL	Valid URL format, Max: 1000 characters
parentCategoryId	UUID	No	Updated parent category ID	Must be existing category UUID

Response JSON Sample:

{
  "success": true,
  "message": "Product category updated successfully",
  "data": {
    "categoryId": "123e4567-e89b-12d3-a456-426614174000",
    "categoryName": "Updated Electronics",
    "categoryDescription": "Updated description for electronics category",
    "categoryIconUrl": "https://example.com/icons/electronics-updated.png",
    "parentCategoryId": "789e0123-e89b-12d3-a456-426614174002",
    "parentCategoryName": "Technology",
    "createdTime": "2025-09-23T10:30:00",
    "editedTime": "2025-09-23T11:45:00",
    "isActive": true,
    "createdBy": "456e7890-e89b-12d3-a456-426614174001",
    "editedBy": "456e7890-e89b-12d3-a456-426614174001"
  }
}

Error Responses:

400 Bad Request: Invalid request data or validation errors
401 Unauthorized: Authentication required
403 Forbidden: Super Admin role required
404 Not Found: Category or parent category not found
409 Conflict: Category name already exists

3. Get Category by ID

Purpose: Retrieves a single product category by its ID

Endpoint: GET /api/v1/products/categories/{categoryId}

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
categoryId	UUID	Yes	ID of category to retrieve	Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Product category retrieved successfully",
  "data": {
    "categoryId": "123e4567-e89b-12d3-a456-426614174000",
    "categoryName": "Electronics",
    "categoryDescription": "All electronic products and accessories",
    "categoryIconUrl": "https://example.com/icons/electronics.png",
    "parentCategoryId": null,
    "parentCategoryName": null,
    "createdTime": "2025-09-23T10:30:00",
    "editedTime": "2025-09-23T10:30:00",
    "isActive": true,
    "createdBy": "456e7890-e89b-12d3-a456-426614174001",
    "editedBy": "456e7890-e89b-12d3-a456-426614174001"
  }
}

Error Responses:

404 Not Found: Category not found

4. Get All Categories

Purpose: Retrieves all product categories with optional filtering by active status

Endpoint: GET /api/v1/products/categories/all

Access Level: 🌐 Public (No authentication required)

Authentication: None

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
isActive	boolean	No	Filter by active status	true/false	All categories

Response JSON Sample:

{
  "success": true,
  "message": "Product categories retrieved successfully",
  "data": [
    {
      "categoryId": "123e4567-e89b-12d3-a456-426614174000",
      "categoryName": "Electronics",
      "categoryDescription": "All electronic products and accessories",
      "categoryIconUrl": "https://example.com/icons/electronics.png",
      "parentCategoryId": null,
      "parentCategoryName": null,
      "createdTime": "2025-09-23T10:30:00",
      "editedTime": "2025-09-23T10:30:00",
      "isActive": true,
      "createdBy": "456e7890-e89b-12d3-a456-426614174001",
      "editedBy": "456e7890-e89b-12d3-a456-426614174001"
    }
  ]
}

Error Responses:

None - Returns empty array if no categories found

5. Get All Categories (Paginated)

Purpose: Retrieves all product categories with pagination and optional filtering

Endpoint: GET /api/v1/products/categories/all-paged

Access Level: 🌐 Public (No authentication required)

Authentication: None

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
isActive	boolean	No	Filter by active status	true/false	All categories
page	integer	No	Page number (1-indexed)	Min: 1	1
size	integer	No	Items per page	Min: 1	10

Response JSON Sample:

{
  "success": true,
  "message": "Product categories retrieved successfully",
  "data": {
    "content": [
      {
        "categoryId": "123e4567-e89b-12d3-a456-426614174000",
        "categoryName": "Electronics",
        "categoryDescription": "All electronic products and accessories",
        "categoryIconUrl": "https://example.com/icons/electronics.png",
        "parentCategory": null,
        "createdTime": "2025-09-23T10:30:00",
        "editedTime": "2025-09-23T10:30:00",
        "isActive": true,
        "createdBy": "456e7890-e89b-12d3-a456-426614174001",
        "editedBy": "456e7890-e89b-12d3-a456-426614174001"
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 10,
      "sort": {
        "sorted": true,
        "orderBy": "createdTime",
        "direction": "DESC"
      }
    },
    "totalElements": 25,
    "totalPages": 3,
    "first": true,
    "last": false,
    "size": 10,
    "number": 0
  }
}

Response Fields:

Field	Description
content	Array of category entities
totalElements	Total number of categories
totalPages	Total number of pages
first	Whether this is the first page
last	Whether this is the last page
size	Number of items per page
number	Current page number (0-indexed)

Error Responses:

None - Returns empty page if no categories found

6. Get Parent Categories

Purpose: Retrieves all active parent categories (categories with no parent)

Endpoint: GET /api/v1/products/categories/parent-categories

Access Level: 🌐 Public (No authentication required)

Authentication: None

Response JSON Sample:

{
  "success": true,
  "message": "Parent categories retrieved successfully",
  "data": [
    {
      "categoryId": "123e4567-e89b-12d3-a456-426614174000",
      "categoryName": "Electronics",
      "categoryDescription": "All electronic products and accessories",
      "categoryIconUrl": "https://example.com/icons/electronics.png",
      "parentCategoryId": null,
      "parentCategoryName": null,
      "createdTime": "2025-09-23T10:30:00",
      "editedTime": "2025-09-23T10:30:00",
      "isActive": true,
      "createdBy": "456e7890-e89b-12d3-a456-426614174001",
      "editedBy": "456e7890-e89b-12d3-a456-426614174001"
    }
  ]
}

Error Responses:

None - Returns empty array if no parent categories found

7. Get Child Categories

Purpose: Retrieves all active child categories for a specific parent category

Endpoint: GET /api/v1/products/categories/parent/{parentId}/children

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
parentId	UUID	Yes	ID of parent category	Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Child categories retrieved successfully",
  "data": [
    {
      "categoryId": "789e0123-e89b-12d3-a456-426614174002",
      "categoryName": "Smartphones",
      "categoryDescription": "Mobile phones and smartphones",
      "categoryIconUrl": "https://example.com/icons/smartphones.png",
      "parentCategoryId": "123e4567-e89b-12d3-a456-426614174000",
      "parentCategoryName": "Electronics",
      "createdTime": "2025-09-23T11:00:00",
      "editedTime": "2025-09-23T11:00:00",
      "isActive": true,
      "createdBy": "456e7890-e89b-12d3-a456-426614174001",
      "editedBy": "456e7890-e89b-12d3-a456-426614174001"
    }
  ]
}

Error Responses:

404 Not Found: Parent category not found

8. Delete Product Category

Purpose: Soft deletes a product category by marking it as inactive

Endpoint: DELETE /api/v1/products/categories/{categoryId}

Access Level: 🔒 Protected (Requires Super Admin role)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
categoryId	UUID	Yes	ID of category to delete	Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Product category deleted successfully"
}

Error Responses:

401 Unauthorized: Authentication required
403 Forbidden: Super Admin role required
404 Not Found: Category not found or already inactive

9. Activate Product Category

Purpose: Reactivates a previously deleted (inactive) product category

Endpoint: PATCH /api/v1/products/categories/{categoryId}/activate

Access Level: 🔒 Protected (Requires Super Admin role)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
categoryId	UUID	Yes	ID of category to activate	Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Product category activated successfully"
}

Error Responses:

401 Unauthorized: Authentication required
403 Forbidden: Super Admin role required
404 Not Found: Category not found or already active

Quick Reference Guide

Common HTTP Status Codes

200 OK: Successful GET/PUT/PATCH request
201 Created: Successful POST request
204 No Content: Successful DELETE request
400 Bad Request: Invalid request data or validation errors
401 Unauthorized: Authentication required/failed
403 Forbidden: Insufficient permissions (Super Admin required)
404 Not Found: Resource not found
409 Conflict: Category name already exists
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server error

Authentication Types

Bearer Token: Include Authorization: Bearer your_token in headers
None: No authentication required for read operations

Data Format Standards

Dates: Use ISO 8601 format (2025-09-23T14:30:00Z)
UUIDs: Use standard UUID format (123e4567-e89b-12d3-a456-426614174000)
Pagination: 1-indexed pages (page starts from 1)
URLs: Must be valid URL format for categoryIconUrl

Validation Rules

Category Name: Required, max 100 characters, must be unique
Category Description: Optional, max 500 characters
Category Icon URL: Optional, valid URL format, max 1000 characters
Parent Category ID: Optional, must be existing category UUID
Page Number: Minimum 1, defaults to 1
Page Size: Minimum 1, defaults to 10

Role-Based Access Control

Public Operations: Get single category, get all categories, get paginated categories, get parent categories, get child categories
Super Admin Operations: Create category, update category, delete category, activate category

Hierarchical Category Structure

Categories can have parent-child relationships
Parent categories have parentCategoryId: null
Child categories reference their parent via parentCategoryId
No limit on nesting depth (be cautious of deep hierarchies)

Shop Categories Management

Shop Management

Shop Rating

Shop Review

Product Management

Cart Management

Wishlist Management

Wallet

Transaction History

Installment Purchase - Customer Endpoints

Installment Purchase - Public & Plan Endpoints

Installment Plan Management - Admin/Shop Endpoints

Shop Categories Management

Endpoints

1. Create Product Category

2. Update Product Category

3. Get Category by ID

4. Get All Categories

5. Get All Categories (Paginated)

6. Get Parent Categories

7. Get Child Categories

8. Delete Product Category

9. Activate Product Category

Quick Reference Guide

Common HTTP Status Codes

Authentication Types

Data Format Standards

Validation Rules

Role-Based Access Control

Hierarchical Category Structure