Shop Management

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

Base URL: https://api.nextgate.com/api/v1

Short Description: The Shop Management API provides comprehensive endpoints for creating, managing, and retrieving shop information within the NextGate platform. This API handles shop registration, updates, approvals, categorization, and includes integrated rating and review data for enhanced shop profiles.

Hints:

All shop operations require proper authentication via Bearer token
Shop creation requires valid category ID and owner authentication
Pagination uses 1-based page numbering (page=1 for first page)
Shop approval operations require SUPER_ADMIN or STAFF_ADMIN roles
Featured shops are randomized on each request for better discovery
Rating and review data is automatically included in shop responses

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-09-23T10:30:45",
  "data": "Error description" // or detailed error object
}

Standard Response Fields

Field	Type	Description
`success`	boolean	Always `true` for successful operations, `false` for errors
`httpStatus`	string	HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
`message`	string	Human-readable message describing the operation result
`action_time`	string	ISO 8601 timestamp of when the response was generated
`data`	object/string	Response payload for success, error details for failures

Endpoints

1. Create Shop

Purpose: Creates a new shop with all required information including owner details, category assignment, and location data

Endpoint: POST {base_url}/shops

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Request Headers:

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

Request JSON Sample:

{
  "shopName": "Mama Lucy's Restaurant",
  "shopDescription": "Authentic Tanzanian cuisine served with love in the heart of Dar es Salaam",
  "tagline": "Taste of home",
  "logoUrl": "https://example.com/logo.jpg",
  "bannerUrl": "https://example.com/banner.jpg",
  "shopImages": [
    "https://example.com/shop1.jpg",
    "https://example.com/shop2.jpg"
  ],
  "categoryId": "550e8400-e29b-41d4-a716-446655440000",
  "shopType": "HYBRID",
  "phoneNumber": "+255123456789",
  "email": "info@mamalucy.co.tz",
  "websiteUrl": "https://mamalucy.co.tz",
  "socialMediaLinks": [
    "https://facebook.com/mamalucy",
    "https://instagram.com/mamalucy"
  ],
  "address": "Msimbazi Street, Block 45",
  "city": "Dar es Salaam",
  "region": "Dar es Salaam",
  "postalCode": "12345",
  "countryCode": "TZ",
  "latitude": -6.7924,
  "longitude": 39.2083,
  "locationNotes": "Near the main bus stop",
  "businessRegistrationNumber": "REG123456",
  "taxNumber": "TAX789012",
  "licenseNumber": "LIC345678",
  "promotionText": "Grand opening - 20% off all meals!"
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
shopName	string	Yes	Name of the shop	Min: 2, Max: 100 characters
shopDescription	string	Yes	Detailed description of the shop	Max: 1000 characters
categoryId	UUID	Yes	Shop category identifier	Must be valid category ID
phoneNumber	string	Yes	Contact phone number	Pattern: ^\+?[0-9]{10,15}$
city	string	Yes	City location	Min: 2, Max: 50 characters
region	string	Yes	Region/state location	Min: 2, Max: 50 characters
tagline	string	No	Short promotional tagline	Max: 50 characters
logoUrl	string	No	URL to shop logo image	Must be valid URL, Max: 1000 chars
bannerUrl	string	No	URL to shop banner image	Must be valid URL, Max: 1000 chars
shopImages	array	No	Array of shop image URLs	Each URL max 1000 chars
shopType	string	No	Type of shop	enum: PHYSICAL, ONLINE, HYBRID (default: HYBRID)
email	string	No	Shop contact email	Must be valid email, Max: 100 chars
websiteUrl	string	No	Shop website URL	Must be valid URL, Max: 200 chars
socialMediaLinks	array	No	Array of social media URLs	Each URL max 500 chars
address	string	No	Street address	Max: 200 characters
postalCode	string	No	Postal/ZIP code	Max: 10 characters
countryCode	string	No	Country code	Max: 3 chars (default: "TZ")
latitude	decimal	No	Latitude coordinate	Range: -90.0 to 90.0
longitude	decimal	No	Longitude coordinate	Range: -180.0 to 180.0
locationNotes	string	No	Additional location details	Max: 300 characters
businessRegistrationNumber	string	No	Business registration number	Max: 50 characters
taxNumber	string	No	Tax identification number	Max: 50 characters
licenseNumber	string	No	Business license number	Max: 50 characters
promotionText	string	No	Current promotion message	Max: 200 characters

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop created successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "shopSlug": "mama-lucys-restaurant",
    "shopDescription": "Authentic Tanzanian cuisine served with love in the heart of Dar es Salaam",
    "tagline": "Taste of home",
    "logoUrl": "https://example.com/logo.jpg",
    "bannerUrl": "https://example.com/banner.jpg",
    "shopImages": [
      "https://example.com/shop1.jpg",
      "https://example.com/shop2.jpg"
    ],
    "ownerId": "456e7890-e89b-12d3-a456-426614174001",
    "ownerName": "Lucy Mwalimu",
    "categoryId": "550e8400-e29b-41d4-a716-446655440000",
    "categoryName": "Restaurant & Food",
    "shopType": "HYBRID",
    "status": "PENDING",
    "phoneNumber": "+255123456789",
    "email": "info@mamalucy.co.tz",
    "websiteUrl": "https://mamalucy.co.tz",
    "socialMediaLinks": [
      "https://facebook.com/mamalucy",
      "https://instagram.com/mamalucy"
    ],
    "address": "Msimbazi Street, Block 45",
    "city": "Dar es Salaam",
    "region": "Dar es Salaam",
    "postalCode": "12345",
    "countryCode": "TZ",
    "latitude": -6.7924,
    "longitude": 39.2083,
    "locationNotes": "Near the main bus stop",
    "businessRegistrationNumber": "REG123456",
    "taxNumber": "TAX789012",
    "licenseNumber": "LIC345678",
    "establishedYear": null,
    "isVerified": false,
    "verificationBadge": null,
    "trustScore": 0.00,
    "lastSeenTime": null,
    "isFeatured": false,
    "featuredUntil": null,
    "promotionText": "Grand opening - 20% off all meals!",
    "isApproved": true,
    "createdAt": "2025-09-23T10:30:45",
    "updatedAt": "2025-09-23T10:30:45",
    "approvedAt": null,
    "averageRating": null,
    "totalRatings": 0,
    "totalActiveReviews": 0,
    "reviews": []
  }
}

Success Response Fields:

Field	Description
shopId	Unique identifier for the shop
shopSlug	URL-friendly version of shop name
status	Shop status (PENDING, ACTIVE, SUSPENDED, CLOSED, UNDER_REVIEW)
isApproved	Whether shop has been approved by admin
averageRating	Average rating score (null if no ratings)
totalRatings	Total number of ratings received
totalActiveReviews	Number of active reviews
reviews	Array of review objects

2. Get All Shops (List)

Purpose: Retrieves all shops in the system without pagination

Endpoint: GET {base_url}/shops/all

Access Level: 🌐 Public (No authentication required)

Authentication: None

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "All shops retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": [
    {
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "Mama Lucy's Restaurant",
      "shopSlug": "mama-lucys-restaurant",
      "averageRating": 4.5,
      "totalRatings": 25,
      "totalActiveReviews": 12,
      "topReviews": [
        {
          "reviewId": "rev-123",
          "userName": "John Doe",
          "reviewText": "Amazing food and great service!",
          "createdAt": "2025-09-22T14:30:00"
        }
      ]
    }
  ]
}

3. Get All Shops (Paginated)

Purpose: Retrieves all shops with pagination support for better performance

Endpoint: GET {base_url}/shops/all-paged

Access Level: 🌐 Public (No authentication required)

Authentication: None

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-based)	Min: 1	1
size	integer	No	Number of items per page	Min: 1, Max: 100	10

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shops retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shops": [
      {
        "shopId": "123e4567-e89b-12d3-a456-426614174000",
        "shopName": "Mama Lucy's Restaurant",
        "averageRating": 4.5,
        "totalRatings": 25,
        "city": "Dar es Salaam",
        "region": "Dar es Salaam"
      }
    ],
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 150,
    "totalPages": 15,
    "hasNext": true,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": false
  }
}

4. Update Shop

Purpose: Updates shop information (only shop owners can update their shops)

Endpoint: PUT {base_url}/shops/{shopId}

Access Level: 🔒 Protected (Shop Owner Only)

Authentication: Bearer Token

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Must be valid UUID

Request Headers:

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

Request JSON Sample:

{
	"shopName": "Mama Juma's Kitchen - Tabora",
	"shopDescription": "Authentic Tanzanian cuisine with fresh ingredients and traditional recipes passed down through generations. We specialize in local dishes like ugali, nyama choma, and pilau.",
	"logoUrl": "https://example.com/images/mama-juma-logo.jpg",
	"categoryId": "fec6a097-612c-470c-af4f-4807e24bef9a",
	"phoneNumber": "+255712345678",
	"city": "Dar es Salaam",
	"region": "Dar es Salaam",
	"tagline": "Taste of Home",
	"shopImages": [
		"https://example.com/images/shop-front.jpg",
		"https://example.com/images/kitchen.jpg"
	],
	"bannerUrl": "https://example.com/images/banner.jpg",
	"shopType": "ONLINE",
	"email": "info@mamajuma.co.tz",
	"websiteUrl": "https://mamajuma.co.tz",
	"socialMediaLinks": [
		"https://facebook.com/mamajuma",
		"https://instagram.com/mamajuma"
	],
	"address": "123 Msimbazi Street, Kariakoo",
	"postalCode": "11101",
	"businessRegistrationNumber": "VRI19939",
	"taxNumber": "TAX9482",
	"countryCode": "TZ",
	"latitude": -6.8160,
	"longitude": 39.2803,
	"locationNotes": "Near Kariakoo Market, opposite the blue building",
	"promotionText": "Free delivery within 5km for orders above 20,000 TSH"
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
shopName	string	No	Updated shop name	Min: 2, Max: 100 characters
shopDescription	string	No	Updated description	Max: 1000 characters
tagline	string	No	Updated tagline	Max: 50 characters
logoUrl	string	No	Updated logo URL	Must be valid URL
bannerUrl	string	No	Updated banner URL	Must be valid URL
shopImages	array	No	Updated shop images	Array of valid URLs
categoryId	UUID	No	Updated category	Must be valid category ID
shopType	string	No	Updated shop type	enum: PHYSICAL, ONLINE, HYBRID
phoneNumber	string	No	Updated phone number	Pattern: ^\+?[0-9]{10,15}$
email	string	No	Updated email	Must be valid email
websiteUrl	string	No	Updated website URL	Must be valid URL
socialMediaLinks	array	No	Updated social media links	Array of valid URLs
address	string	No	Updated address	Max: 200 characters
city	string	No	Updated city	Min: 2, Max: 50 characters
region	string	No	Updated region	Min: 2, Max: 50 characters
postalCode	string	No	Updated postal code	Max: 10 characters
countryCode	string	No	Updated country code	Max: 3 characters
latitude	decimal	No	Updated latitude	Range: -90.0 to 90.0
longitude	decimal	No	Updated longitude	Range: -180.0 to 180.0
locationNotes	string	No	Updated location notes	Max: 300 characters
promotionText	string	No	Updated promotion text	Max: 200 characters

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop updated successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Premium Restaurant",
    "shopSlug": "mama-lucys-premium-restaurant",
    "updatedAt": "2025-09-23T10:30:45"
  }
}

5. Get Shop by ID (Summary)

Purpose: Retrieves basic shop information by shop ID

Endpoint: GET {base_url}/shops/{shopId}

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Must be valid UUID

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "shopSlug": "mama-lucys-restaurant",
    "shopDescription": "Authentic Tanzanian cuisine",
    "logoUrl": "https://example.com/logo.jpg",
    "averageRating": 4.5,
    "totalRatings": 25,
    "totalActiveReviews": 12,
    "city": "Dar es Salaam",
    "region": "Dar es Salaam",
    "isVerified": false,
    "trustScore": 8.5
  }
}

6. Get Shop by ID (Detailed)

Purpose: Retrieves complete shop information including sensitive business details (owner/admin access only)

Endpoint: GET {base_url}/shops/{shopId}/detailed

Access Level: 🔒 Protected (Shop Owner or Admin Only)

Authentication: Bearer Token

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Must be valid UUID

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authenticated user

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "businessRegistrationNumber": "REG123456",
    "taxNumber": "TAX789012",
    "licenseNumber": "LIC345678",
    "averageRating": 4.5,
    "totalRatings": 25,
    "reviews": [
      {
        "reviewId": "rev-123",
        "userName": "John Doe",
        "reviewText": "Amazing food!",
        "status": "ACTIVE",
        "createdAt": "2025-09-22T14:30:00"
      }
    ]
  }
}

7. Get My Shops

Purpose: Retrieves all shops owned by the authenticated user

Endpoint: GET {base_url}/shops/my-shops

Access Level: 🔒 Protected (Authenticated User Only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authenticated user

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "My shops retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": [
    {
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "Mama Lucy's Restaurant",
      "status": "ACTIVE",
      "isApproved": true,
      "averageRating": 4.5,
      "totalRatings": 25,
      "createdAt": "2025-09-20T10:30:45"
    }
  ]
}

8. Get My Shops (Paginated)

Purpose: Retrieves user's shops with pagination support

Endpoint: GET {base_url}/shops/my-shops-paged

Access Level: 🔒 Protected (Authenticated User Only)

Authentication: Bearer Token

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-based)	Min: 1	1
size	integer	No	Number of items per page	Min: 1, Max: 100	10

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authenticated user

9. Approve Shop

Purpose: Approve or reject a shop (admin operation)

Endpoint: PATCH {base_url}/shops/{shopId}/approve-shop

Access Level: 🔒 Protected (Super Admin or Staff Admin Only)

Authentication: Bearer Token

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Must be valid UUID

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
approve	boolean	Yes	Whether to approve (true) or reject (false)	Must be boolean	-

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for admin user

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop approval status changed successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "isApproved": true,
    "approvedAt": "2025-09-23T10:30:45"
  }
}

10. Get Shops by Category

Purpose: Retrieves all shops in a specific category

Endpoint: GET {base_url}/shops/category/{categoryId}

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
categoryId	UUID	Yes	Unique identifier of the shop category	Must be valid UUID

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shops by category retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": [
    {
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "Mama Lucy's Restaurant",
      "categoryName": "Restaurant & Food",
      "averageRating": 4.5,
      "city": "Dar es Salaam"
    }
  ]
}

11. Get Shops by Category (Paginated)

Purpose: Retrieves shops in a category with pagination

Endpoint: GET {base_url}/shops/category/{categoryId}/paged

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
categoryId	UUID	Yes	Unique identifier of the shop category	Must be valid UUID

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-based)	Min: 1	1
size	integer	No	Number of items per page	Min: 1, Max: 100	10

12. Get Featured Shops

Purpose: Retrieves randomly selected featured shops (up to 20 shops)

Endpoint: GET {base_url}/shops/featured

Access Level: 🌐 Public (No authentication required)

Authentication: None

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Featured shops retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": [
    {
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "Mama Lucy's Restaurant",
      "averageRating": 4.5,
      "totalRatings": 25,
      "city": "Dar es Salaam",
      "isVerified": true
    }
  ]
}

13. Get Featured Shops (Paginated)

Purpose: Retrieves featured shops with pagination (randomized on each request)

Endpoint: GET {base_url}/shops/featured-paged

Access Level: 🌐 Public (No authentication required)

Authentication: None

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-based)	Min: 1	1
size	integer	No	Number of items per page	Min: 1, Max: 100	10

14. Get Shop Summary Statistics

Purpose: Retrieves comprehensive statistics including ratings, reviews, and user activities for a shop

Endpoint: GET {base_url}/shops/{shopId}/summary-stats

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Must be valid UUID

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop summary stats retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "averageRating": 4.5,
    "totalRatings": 25,
    "ratingDistribution": {
      "1": 1,
      "2": 2,
      "3": 5,
      "4": 7,
      "5": 10
    },
    "totalReviews": 15,
    "activeReviews": 12,
    "hiddenReviews": 2,
    "flaggedReviews": 1,
    "userActivities": [
      {
        "userId": "user-123",
        "userName": "John Doe",
        "reviewId": "rev-123",
        "reviewText": "Amazing food and service!",
        "reviewStatus": "ACTIVE",
        "reviewDate": "2025-09-22T14:30:00",
        "ratingId": "rat-123",
        "ratingValue": 5,
        "ratingDate": "2025-09-22T14:35:00",
        "hasReview": true,
        "hasRating": true
      }
    ]
  }
}

Success Response Fields:

Field	Description
shopId	Unique identifier of the shop
shopName	Name of the shop
averageRating	Average rating score (1-5)
totalRatings	Total number of ratings received
ratingDistribution	Count of ratings by star value (1-5)
totalReviews	Total number of reviews (all statuses)
activeReviews	Number of active/visible reviews
hiddenReviews	Number of hidden reviews
flaggedReviews	Number of flagged reviews
userActivities	Array of combined user review and rating activities
userActivities.hasReview	Whether user has written a review
userActivities.hasRating	Whether user has given a rating

Standard Error Types and Responses

Application-Level Exceptions (400-499)

400 BAD_REQUEST: General invalid request data, random exceptions, or item already exists
401 UNAUTHORIZED: Authentication issues (empty, invalid, expired, or malformed tokens)
403 FORBIDDEN: Access denied, permission issues, verification failures, expired invitations
404 NOT_FOUND: Requested resource does not exist
422 UNPROCESSABLE_ENTITY: Validation errors with detailed field information
429 TOO_MANY_REQUESTS: Rate limit exceeded

Server-Level Exceptions (500+)

500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Shop Already Exists (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Shop with this name already exists",
  "action_time": "2025-09-23T10:30:45",
  "data": "Shop with this name already exists"
}

Unauthorized - Token Issues (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Token has expired",
  "action_time": "2025-09-23T10:30:45",
  "data": "Token has expired"
}

Access Denied - Insufficient Permissions (403):

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Access denied: Insufficient permissions",
  "action_time": "2025-09-23T10:30:45",
  "data": "Access denied: Insufficient permissions"
}

Shop Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Shop not found",
  "action_time": "2025-09-23T10:30:45",
  "data": "Shop not found"
}

Category Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Shop category not found",
  "action_time": "2025-09-23T10:30:45",
  "data": "Shop category not found"
}

User Not Authenticated (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not authenticated",
  "action_time": "2025-09-23T10:30:45",
  "data": "User not authenticated"
}

Validation Error (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopName": "Shop name must be between 2 and 100 characters",
    "phoneNumber": "Phone number must be between 10-15 digits and may start with +",
    "email": "Email must be valid"
  }
}

Random Business Logic Error (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Only shop owners can update their shops",
  "action_time": "2025-09-23T10:30:45",
  "data": "Only shop owners can update their shops"
}

Cannot Update Deleted Shop (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot update a deleted shop",
  "action_time": "2025-09-23T10:30:45",
  "data": "Cannot update a deleted shop"
}

Data Models and Enums

Shop Status Enum

Value	Description
`PENDING`	Awaiting admin approval
`ACTIVE`	Active and operational
`SUSPENDED`	Temporarily suspended by admin
`CLOSED`	Permanently closed/inactive
`UNDER_REVIEW`	Under admin review for policy violations

Shop Type Enum

Value	Description
`PHYSICAL`	Physical store only (brick-and-mortar)
`ONLINE`	Online store only (e-commerce)
`HYBRID`	Both physical and online presence

Verification Badge Enum

Value	Description
`BRONZE`	Basic verification (documents verified)
`SILVER`	Enhanced verification (business registration + documents)
`GOLD`	Premium verification (full compliance + good track record)
`PREMIUM`	Highest level (partner status + excellent performance)

Review Status Enum (from related services)

Value	Description
`ACTIVE`	Review is visible and active
`HIDDEN`	Review is hidden from public view
`FLAGGED`	Review has been flagged for review
`DELETED`	Review has been deleted

Business Rules and Logic

Shop Creation Rules

Shop name must be unique across all active shops
Shop slug is automatically generated from shop name and must be unique
New shops are automatically set to PENDING status
Shop owner is automatically set to the authenticated user
Shop approval is automatically set to true in current implementation
Default country code is "TZ" (Tanzania)
Default shop type is "HYBRID"

Shop Update Rules

Only shop owners can update their own shops
Shop name changes trigger automatic slug regeneration
Deleted shops cannot be updated
Category ID must exist and be valid
Phone number and email validation applies on updates

Shop Approval Rules

Only users with ROLE_SUPER_ADMIN or ROLE_STAFF_ADMIN can approve shops
Approval status change is tracked with timestamp and admin user
Approved shops can be featured in search results

Access Control Rules

Public endpoints: Shop listings, shop details (summary), categories, featured shops
Authenticated user: Create shop, update own shop, view own shops
Admin only: Approve/reject shops, view detailed shop information for all shops
Owner/Admin only: View detailed shop information with business details

Rating and Review Integration

Shop responses automatically include rating summaries (average, total count)
Shop responses include review summaries (total active reviews, top reviews)
Summary statistics combine ratings and reviews from related services
User activities show combined review and rating history per user

Pagination Rules

Page numbers are 1-based (first page is page=1)
Default page size is 10 items
Maximum page size is 100 items
Invalid page numbers default to page 1
Invalid page sizes default to 10

Featured Shops Logic

Featured shops are randomly selected from all approved, active shops
Non-paginated featured endpoint returns up to 20 shops
Paginated featured endpoint maintains randomization across requests
Featured status can be time-limited (featuredUntil field)

Authentication and Authorization

Bearer Token Authentication

Include the Bearer token in the Authorization header for protected endpoints:

Authorization: Bearer your_jwt_token_here

Required Roles for Admin Operations

Shop Approval: Requires ROLE_SUPER_ADMIN or ROLE_STAFF_ADMIN
Detailed Shop Access: Shop owner or admin roles
Shop Updates: Shop owner only

Token Validation

Tokens are validated on each request to protected endpoints
Expired tokens return 401 Unauthorized
Invalid or malformed tokens return 401 Unauthorized
Missing tokens on protected endpoints return 401 Unauthorized

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 Management

Standard Response Format

Success Response Structure

Error Response Structure

Standard Response Fields

Endpoints

1. Create Shop

2. Get All Shops (List)

3. Get All Shops (Paginated)

4. Update Shop

5. Get Shop by ID (Summary)

6. Get Shop by ID (Detailed)

7. Get My Shops

8. Get My Shops (Paginated)

9. Approve Shop

10. Get Shops by Category

11. Get Shops by Category (Paginated)

12. Get Featured Shops

13. Get Featured Shops (Paginated)

14. Get Shop Summary Statistics

Standard Error Types and Responses

Application-Level Exceptions (400-499)

Server-Level Exceptions (500+)

Data Models and Enums

Shop Status Enum

Shop Type Enum

Verification Badge Enum

Review Status Enum (from related services)

Business Rules and Logic

Shop Creation Rules

Shop Update Rules

Shop Approval Rules

Access Control Rules

Rating and Review Integration

Pagination Rules

Featured Shops Logic

Authentication and Authorization

Bearer Token Authentication

Required Roles for Admin Operations

Token Validation