Shop Categories

Author: NextGate Development Team, Backend Engineers Last Updated: 2025-09-22 Version: v1.0

Short Description: The Shop Categories API provides comprehensive functionality for managing shop categories. It enables administrators to create, update, and manage shop categories that are used to organize shops into different business types and industries.

Hints:

  • All category management endpoints require SUPER_ADMIN role

  • Category names must be unique across the system

  • Soft delete is implemented - deleted categories are marked as inactive but not removed

  • Category icons should be provided as valid URLs

  • Getting categories (all/paged) endpoints are public and don't require authentication

Endpoints

1. Create Shop Category

Purpose: Creates a new shop category (Admin only)

Endpoint: POST /api/v1/shops/categories

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

Request JSON Sample:

{
  "categoryName": "Electronics",
  "categoryDescription": "Electronic goods and gadgets",
  "categoryIconUrl": "https://example.com/icons/electronics.png"
}

Request Body Parameters:

Parameter
Type
Required
Description
Validation

categoryName

string

Yes

Name of the category

Min: 1, Max: 100 characters, unique

categoryDescription

string

No

Description of the category

Max: 500 characters

categoryIconUrl

string

No

URL for category icon

Valid URL format

Response JSON Sample:

{
  "success": true,
  "message": "Shop category created successfully",
  "data": {
    "categoryId": "550e8400-e29b-41d4-a716-446655440000",
    "categoryName": "Electronics",
    "categoryDescription": "Electronic goods and gadgets",
    "categoryIconUrl": "https://example.com/icons/electronics.png",
    "createdTime": "2025-09-22T14:30:00Z",
    "editedTime": "2025-09-22T14:30:00Z",
    "isActive": true,
    "createdBy": "550e8400-e29b-41d4-a716-446655440001",
    "editedBy": "550e8400-e29b-41d4-a716-446655440001"
  }
}

Response Fields:

Field
Description

categoryId

Unique identifier for the category

categoryName

Name of the category

categoryDescription

Description of the category

categoryIconUrl

URL for category icon

createdTime

Timestamp when category was created

editedTime

Timestamp when category was last edited

isActive

Whether the category is active

createdBy

ID of user who created the category

editedBy

ID of user who last edited the category

Error Responses:

  • 400 Bad Request: Invalid request data or missing required fields

  • 401 Unauthorized: Authentication required/failed

  • 403 Forbidden: Insufficient permissions (not SUPER_ADMIN)

  • 409 Conflict: Category with this name already exists

  • 500 Internal Server Error: Server error

2. Update Shop Category

Purpose: Updates an existing shop category (Admin only)

Endpoint: PUT /api/v1/shops/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 the category to update

Valid UUID format

Request JSON Sample:

{
  "categoryName": "Electronics & Gadgets",
  "categoryDescription": "Electronic goods, gadgets and accessories",
  "categoryIconUrl": "https://example.com/icons/electronics-new.png"
}

Request Body Parameters:

Parameter
Type
Required
Description
Validation

categoryName

string

Yes

Updated name of the category

Min: 1, Max: 100 characters

categoryDescription

string

No

Updated description

Max: 500 characters

categoryIconUrl

string

No

Updated icon URL

Valid URL format

Response JSON Sample:

{
  "success": true,
  "message": "Shop category updated successfully",
  "data": {
    "categoryId": "550e8400-e29b-41d4-a716-446655440000",
    "categoryName": "Electronics & Gadgets",
    "categoryDescription": "Electronic goods, gadgets and accessories",
    "categoryIconUrl": "https://example.com/icons/electronics-new.png",
    "createdTime": "2025-09-22T14:30:00Z",
    "editedTime": "2025-09-22T15:45:00Z",
    "isActive": true,
    "createdBy": "550e8400-e29b-41d4-a716-446655440001",
    "editedBy": "550e8400-e29b-41d4-a716-446655440001"
  }
}

Error Responses:

  • 400 Bad Request: Invalid request data

  • 401 Unauthorized: Authentication required/failed

  • 403 Forbidden: Insufficient permissions

  • 404 Not Found: Category not found

  • 409 Conflict: Category name already exists

  • 500 Internal Server Error: Server error

3. Get Shop Category by ID

Purpose: Retrieves a specific shop category by its ID (Admin only)

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

Access Level: 🔒 Protected (Requires SUPER_ADMIN role)

Authentication: Bearer Token

Path Parameters:

Parameter
Type
Required
Description
Validation

categoryId

UUID

Yes

ID of the category to retrieve

Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Shop category fetched successfully",
  "data": {
    "categoryId": "550e8400-e29b-41d4-a716-446655440000",
    "categoryName": "Electronics",
    "categoryDescription": "Electronic goods and gadgets",
    "categoryIconUrl": "https://example.com/icons/electronics.png",
    "createdTime": "2025-09-22T14:30:00Z",
    "editedTime": "2025-09-22T14:30:00Z",
    "isActive": true,
    "createdBy": "550e8400-e29b-41d4-a716-446655440001",
    "editedBy": "550e8400-e29b-41d4-a716-446655440001"
  }
}

Error Responses:

  • 401 Unauthorized: Authentication required/failed

  • 403 Forbidden: Insufficient permissions

  • 404 Not Found: Category not found

  • 500 Internal Server Error: Server error

4. Get All Shop Categories

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

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

Access Level: 🌐 Public

Authentication: None

Query Parameters:

Parameter
Type
Required
Description
Validation
Default

isActive

boolean

No

Filter by active status

true or false

null (all)

Response JSON Sample:

{
  "success": true,
  "message": "All shop categories fetched successfully",
  "data": [
    {
      "categoryId": "550e8400-e29b-41d4-a716-446655440000",
      "categoryName": "Electronics",
      "categoryDescription": "Electronic goods and gadgets",
      "categoryIconUrl": "https://example.com/icons/electronics.png",
      "createdTime": "2025-09-22T14:30:00Z",
      "editedTime": "2025-09-22T14:30:00Z",
      "isActive": true,
      "createdBy": "550e8400-e29b-41d4-a716-446655440001",
      "editedBy": "550e8400-e29b-41d4-a716-446655440001"
    },
    {
      "categoryId": "550e8400-e29b-41d4-a716-446655440002",
      "categoryName": "Clothing & Fashion",
      "categoryDescription": "Clothing, accessories and fashion items",
      "categoryIconUrl": "https://example.com/icons/fashion.png",
      "createdTime": "2025-09-22T13:15:00Z",
      "editedTime": "2025-09-22T13:15:00Z",
      "isActive": true,
      "createdBy": "550e8400-e29b-41d4-a716-446655440001",
      "editedBy": "550e8400-e29b-41d4-a716-446655440001"
    }
  ]
}

Error Responses:

  • 500 Internal Server Error: Server error

5. Get Shop Categories (Paginated)

Purpose: Retrieves shop categories with pagination and optional filtering

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

Access Level: 🌐 Public

Authentication: None

Query Parameters:

Parameter
Type
Required
Description
Validation
Default

isActive

boolean

No

Filter by active status

true or false

null

page

integer

No

Page number (1-based)

Min: 1

1

size

integer

No

Number of items per page

Min: 1, Max: 100

10

Response JSON Sample:

{
  "success": true,
  "message": "Shop categories retrieved successfully",
  "data": {
    "content": [
      {
        "categoryId": "550e8400-e29b-41d4-a716-446655440000",
        "categoryName": "Electronics",
        "categoryDescription": "Electronic goods and gadgets",
        "categoryIconUrl": "https://example.com/icons/electronics.png",
        "createdTime": "2025-09-22T14:30:00Z",
        "editedTime": "2025-09-22T14:30:00Z",
        "isActive": true,
        "createdBy": "550e8400-e29b-41d4-a716-446655440001",
        "editedBy": "550e8400-e29b-41d4-a716-446655440001"
      }
    ],
    "pageable": {
      "sort": {
        "sorted": true,
        "unsorted": false
      },
      "pageNumber": 0,
      "pageSize": 10
    },
    "totalElements": 5,
    "totalPages": 1,
    "last": true,
    "first": true,
    "numberOfElements": 5,
    "size": 10,
    "number": 0,
    "empty": false
  }
}

Error Responses:

  • 500 Internal Server Error: Server error

6. Delete Shop Category

Purpose: Soft deletes a shop category (sets isActive to false)

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

Access Level: 🔒 Protected (Requires SUPER_ADMIN role)

Authentication: Bearer Token

Path Parameters:

Parameter
Type
Required
Description
Validation

categoryId

UUID

Yes

ID of the category to delete

Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Shop category deleted successfully",
  "data": "Shop category deleted successfully"
}

Error Responses:

  • 401 Unauthorized: Authentication required/failed

  • 403 Forbidden: Insufficient permissions

  • 404 Not Found: Category not found or already inactive

  • 500 Internal Server Error: Server error

7. Activate Shop Category

Purpose: Activates a previously deactivated shop category

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

Access Level: 🔒 Protected (Requires SUPER_ADMIN role)

Authentication: Bearer Token

Path Parameters:

Parameter
Type
Required
Description
Validation

categoryId

UUID

Yes

ID of the category to activate

Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Shop category activated successfully",
  "data": "Shop category activated successfully"
}

Error Responses:

  • 401 Unauthorized: Authentication required/failed

  • 403 Forbidden: Insufficient permissions

  • 404 Not Found: Category not found or already active

  • 500 Internal Server Error: Server error

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

  • 401 Unauthorized: Authentication required/failed

  • 403 Forbidden: Insufficient permissions

  • 404 Not Found: Resource not found

  • 409 Conflict: Resource already exists

  • 422 Unprocessable Entity: Validation errors

  • 429 Too Many Requests: Rate limit exceeded

  • 500 Internal Server Error: Server error

Authentication Types

  • Bearer Token: Include Authorization: Bearer your_token in headers

  • None: No authentication required

Data Format Standards

  • Dates: Use ISO 8601 format (2025-09-22T14:30:00Z)

  • UUIDs: Use standard UUID format (550e8400-e29b-41d4-a716-446655440000)

  • Pagination: Uses 1-based indexing (page=1 for first page)

  • Boolean Values: Use true/false (lowercase)

Business Rules

  • Category Creation: Only SUPER_ADMIN users can create categories

  • Category Names: Must be unique across the entire system

  • Soft Delete: Categories are marked as inactive (isActive=false) but not physically removed

  • Icon URLs: Should be valid, publicly accessible image URLs

  • Description: Optional but recommended for better category understanding

PreviousShops Management ServiceNextShop Management

Last updated