Shop Management

The Shop Management API provides comprehensive functionality for managing shops, including CRUD operations, approval workflows, and integrated rating/review summaries.

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

Short Description: The Shop Management API provides comprehensive functionality for creating, managing, and retrieving shop information. It enables shop owners to register their businesses, update shop details, and manage their shop profiles, while allowing administrators to approve shops and users to discover shops by various criteria.

Hints:

  • Shop names must be unique across the system

  • Shop slugs are auto-generated from shop names and must be unique

  • New shops are auto-approved but can be manually managed by admins

  • Shop owners can only update their own shops

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

  • Featured shops are randomized from approved shops

  • Soft delete is implemented - deleted shops are marked but not removed

  • Location coordinates should use decimal degrees format

Endpoints

1. Create Shop

Purpose: Creates a new shop

Endpoint: POST /api/v1/shops

Access Level: 🔒 Protected (Requires authentication)

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:

{
  "shopName": "Tech Paradise",
  "shopDescription": "Your one-stop shop for all electronic needs and gadgets",
  "logoUrl": "https://example.com/logos/tech-paradise.png",
  "categoryId": "550e8400-e29b-41d4-a716-446655440000",
  "phoneNumber": "+255123456789",
  "city": "Dar es Salaam",
  "region": "Dar es Salaam",
  "tagline": "Technology at your fingertips",
  "shopImages": ["https://example.com/images/shop1.jpg", "https://example.com/images/shop2.jpg"],
  "bannerUrl": "https://example.com/banners/tech-paradise.jpg",
  "shopType": "HYBRID",
  "email": "info@techparadise.co.tz",
  "websiteUrl": "https://techparadise.co.tz",
  "socialMediaLinks": ["https://facebook.com/techparadise", "https://instagram.com/techparadise"],
  "address": "Kariakoo Street 123",
  "postalCode": "12345",
  "countryCode": "TZ",
  "latitude": -6.8160,
  "longitude": 39.2803,
  "locationNotes": "Near the main bus station, blue building",
  "businessRegistrationNumber": "REG123456",
  "taxNumber": "TAX789012",
  "licenseNumber": "LIC345678",
  "promotionText": "Grand opening - 20% off everything!"
}

Request Body Parameters:

Parameter
Type
Required
Description
Validation

shopName

string

Yes

Name of the shop

Min: 2, Max: 100 characters, unique

shopDescription

string

Yes

Description of the shop

Max: 1000 characters

logoUrl

string

No

URL for shop logo

Valid URL format

categoryId

UUID

Yes

ID of shop category

Valid UUID, category must exist

phoneNumber

string

Yes

Shop phone number

10-15 digits, may start with +

city

string

Yes

Shop city

Min: 2, Max: 50 characters

region

string

Yes

Shop region

Min: 2, Max: 50 characters

tagline

string

No

Shop tagline

Max: 50 characters

shopImages

array

No

Array of shop image URLs

Valid URLs

bannerUrl

string

No

Shop banner URL

Valid URL format

shopType

string

No

Type of shop

enum: PHYSICAL, ONLINE, HYBRID

email

string

No

Shop email

Valid email format

websiteUrl

string

No

Shop website URL

Valid URL format

socialMediaLinks

array

No

Social media URLs

Valid URLs

address

string

No

Shop address

Max: 200 characters

postalCode

string

No

Postal code

Max: 10 characters

countryCode

string

No

Country code

Max: 3 characters

latitude

decimal

No

Shop latitude

Between -90 and 90

longitude

decimal

No

Shop longitude

Between -180 and 180

locationNotes

string

No

Additional location info

Max: 300 characters

businessRegistrationNumber

string

No

Business registration number

Max: 50 characters

taxNumber

string

No

Tax number

Max: 50 characters

licenseNumber

string

No

License number

Max: 50 characters

promotionText

string

No

Promotional text

Max: 200 characters

Response JSON Sample:

{
  "success": true,
  "message": "Shop created successfully",
  "data": {
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise",
    "shopSlug": "tech-paradise",
    "shopDescription": "Your one-stop shop for all electronic needs and gadgets",
    "tagline": "Technology at your fingertips",
    "logoUrl": "https://example.com/logos/tech-paradise.png",
    "ownerId": "550e8400-e29b-41d4-a716-446655440001",
    "ownerName": "John Doe",
    "categoryId": "550e8400-e29b-41d4-a716-446655440000",
    "categoryName": "Electronics",
    "shopType": "HYBRID",
    "status": "PENDING",
    "phoneNumber": "+255123456789",
    "city": "Dar es Salaam",
    "region": "Dar es Salaam",
    "isApproved": true,
    "createdAt": "2025-09-22T14:30:00Z",
    "updatedAt": "2025-09-22T14:30:00Z",
    "averageRating": 0.0,
    "totalRatings": 0,
    "totalActiveReviews": 0
  }
}

Response Fields:

Field
Description

shopId

Unique identifier for the shop

shopName

Name of the shop

shopSlug

URL-friendly slug generated from shop name

shopDescription

Description of the shop

tagline

Shop tagline

logoUrl

URL for shop logo

ownerId

ID of the shop owner

ownerName

Full name of the shop owner

categoryId

ID of the shop category

categoryName

Name of the shop category

shopType

Type of shop (PHYSICAL, ONLINE, HYBRID)

status

Current shop status

phoneNumber

Shop contact phone number

city

Shop city

region

Shop region

isApproved

Whether the shop is approved

createdAt

Timestamp when shop was created

updatedAt

Timestamp when shop was last updated

averageRating

Average rating (0.0 for new shops)

totalRatings

Total number of ratings

totalActiveReviews

Total number of active reviews

Error Responses:

  • 400 Bad Request: Invalid request data or validation errors

  • 401 Unauthorized: Authentication required/failed

  • 404 Not Found: Category not found

  • 409 Conflict: Shop with this name already exists

  • 500 Internal Server Error: Server error

2. Get All Shops

Purpose: Retrieves all shops (non-paginated)

Endpoint: GET /api/v1/shops/all

Access Level: 🌐 Public

Authentication: None

Response JSON Sample:

{
  "success": true,
  "message": "All shops retrieved successfully",
  "data": [
    {
      "shopId": "550e8400-e29b-41d4-a716-446655440002",
      "shopName": "Tech Paradise",
      "shopSlug": "tech-paradise",
      "shopDescription": "Your one-stop shop for all electronic needs",
      "logoUrl": "https://example.com/logos/tech-paradise.png",
      "ownerId": "550e8400-e29b-41d4-a716-446655440001",
      "ownerName": "John Doe",
      "categoryId": "550e8400-e29b-41d4-a716-446655440000",
      "categoryName": "Electronics",
      "status": "ACTIVE",
      "city": "Dar es Salaam",
      "region": "Dar es Salaam",
      "isApproved": true,
      "averageRating": 4.5,
      "totalRatings": 23,
      "totalActiveReviews": 15,
      "topReviews": []
    }
  ]
}

Error Responses:

  • 500 Internal Server Error: Server error

3. Get All Shops (Paginated)

Purpose: Retrieves all shops with pagination

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

Access Level: 🌐 Public

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

Response JSON Sample:

{
  "success": true,
  "message": "Shops retrieved successfully",
  "data": {
    "shops": [
      {
        "shopId": "550e8400-e29b-41d4-a716-446655440002",
        "shopName": "Tech Paradise",
        "shopSlug": "tech-paradise",
        "categoryName": "Electronics",
        "averageRating": 4.5,
        "totalRatings": 23,
        "city": "Dar es Salaam"
      }
    ],
    "currentPage": 0,
    "pageSize": 10,
    "totalElements": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": false
  }
}

Error Responses:

  • 500 Internal Server Error: Server error

4. Update Shop

Purpose: Updates an existing shop (Owner only)

Endpoint: PUT /api/v1/shops/{shopId}

Access Level: 🔒 Protected (Shop owner only)

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

shopId

UUID

Yes

ID of the shop to update

Valid UUID format

Request JSON Sample:

{
  "shopName": "Tech Paradise Pro",
  "shopDescription": "Premium electronics and gadgets store",
  "tagline": "Premium technology solutions",
  "logoUrl": "https://example.com/logos/tech-paradise-pro.png",
  "categoryId": "550e8400-e29b-41d4-a716-446655440000",
  "shopType": "HYBRID",
  "phoneNumber": "+255123456790",
  "email": "contact@techparadisepro.co.tz",
  "websiteUrl": "https://techparadisepro.co.tz",
  "address": "Kariakoo Street 125",
  "city": "Dar es Salaam",
  "region": "Dar es Salaam"
}

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

Valid URL format

categoryId

UUID

No

Updated category ID

Valid UUID

shopType

string

No

Updated shop type

enum: PHYSICAL, ONLINE, HYBRID

phoneNumber

string

No

Updated phone number

10-15 digits, may start with +

email

string

No

Updated email

Valid email format

websiteUrl

string

No

Updated website URL

Valid URL format

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

Response JSON Sample:

{
  "success": true,
  "message": "Shop updated successfully",
  "data": {
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise Pro",
    "shopSlug": "tech-paradise-pro",
    "shopDescription": "Premium electronics and gadgets store",
    "tagline": "Premium technology solutions",
    "updatedAt": "2025-09-22T15:45:00Z"
  }
}

Error Responses:

  • 400 Bad Request: Invalid request data

  • 401 Unauthorized: Authentication required/failed

  • 403 Forbidden: Not the shop owner

  • 404 Not Found: Shop not found

  • 500 Internal Server Error: Server error

5. Get Shop by ID (Summary)

Purpose: Retrieves basic shop information by ID

Endpoint: GET /api/v1/shops/{shopId}

Access Level: 🌐 Public

Authentication: None

Path Parameters:

Parameter
Type
Required
Description
Validation

shopId

UUID

Yes

ID of the shop to retrieve

Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Shop retrieved successfully",
  "data": {
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise",
    "shopSlug": "tech-paradise",
    "shopDescription": "Your one-stop shop for all electronic needs",
    "logoUrl": "https://example.com/logos/tech-paradise.png",
    "ownerId": "550e8400-e29b-41d4-a716-446655440001",
    "ownerName": "John Doe",
    "categoryId": "550e8400-e29b-41d4-a716-446655440000",
    "categoryName": "Electronics",
    "status": "ACTIVE",
    "city": "Dar es Salaam",
    "region": "Dar es Salaam",
    "averageRating": 4.5,
    "totalRatings": 23,
    "totalActiveReviews": 15
  }
}

Error Responses:

  • 404 Not Found: Shop not found

  • 500 Internal Server Error: Server error

6. Get Shop by ID (Detailed)

Purpose: Retrieves detailed shop information (Owner and Admin only)

Endpoint: GET /api/v1/shops/{shopId}/detailed

Access Level: 🔒 Protected (Shop owner or Admin only)

Authentication: Bearer Token

Request Headers:

Header
Type
Required
Description

Authorization

string

Yes

Bearer token for authentication

Path Parameters:

Parameter
Type
Required
Description
Validation

shopId

UUID

Yes

ID of the shop to retrieve

Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Shop retrieved successfully",
  "data": {
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise",
    "shopSlug": "tech-paradise",
    "shopDescription": "Your one-stop shop for all electronic needs",
    "tagline": "Technology at your fingertips",
    "logoUrl": "https://example.com/logos/tech-paradise.png",
    "bannerUrl": "https://example.com/banners/tech-paradise.jpg",
    "shopImages": ["https://example.com/images/shop1.jpg"],
    "ownerId": "550e8400-e29b-41d4-a716-446655440001",
    "ownerName": "John Doe",
    "categoryId": "550e8400-e29b-41d4-a716-446655440000",
    "categoryName": "Electronics",
    "shopType": "HYBRID",
    "status": "ACTIVE",
    "phoneNumber": "+255123456789",
    "email": "info@techparadise.co.tz",
    "websiteUrl": "https://techparadise.co.tz",
    "socialMediaLinks": ["https://facebook.com/techparadise"],
    "address": "Kariakoo Street 123",
    "city": "Dar es Salaam",
    "region": "Dar es Salaam",
    "postalCode": "12345",
    "countryCode": "TZ",
    "latitude": -6.8160,
    "longitude": 39.2803,
    "locationNotes": "Near the main bus station",
    "businessRegistrationNumber": "REG123456",
    "taxNumber": "TAX789012",
    "licenseNumber": "LIC345678",
    "establishedYear": null,
    "isVerified": false,
    "verificationBadge": null,
    "trustScore": 0.0,
    "lastSeenTime": null,
    "isFeatured": false,
    "featuredUntil": null,
    "promotionText": "Grand opening - 20% off everything!",
    "createdAt": "2025-09-22T14:30:00Z",
    "updatedAt": "2025-09-22T14:30:00Z",
    "approvedAt": null,
    "isApproved": true,
    "averageRating": 4.5,
    "totalRatings": 23,
    "totalActiveReviews": 15,
    "reviews": []
  }
}

Error Responses:

  • 401 Unauthorized: Authentication required/failed

  • 403 Forbidden: Not authorized to view detailed information

  • 404 Not Found: Shop not found

  • 500 Internal Server Error: Server error

7. Get My Shops

Purpose: Retrieves all shops owned by the authenticated user

Endpoint: GET /api/v1/shops/my-shops

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header
Type
Required
Description

Authorization

string

Yes

Bearer token for authentication

Response JSON Sample:

{
  "success": true,
  "message": "My shops retrieved successfully",
  "data": [
    {
      "shopId": "550e8400-e29b-41d4-a716-446655440002",
      "shopName": "Tech Paradise",
      "shopSlug": "tech-paradise",
      "status": "ACTIVE",
      "isApproved": true,
      "averageRating": 4.5,
      "totalRatings": 23,
      "totalActiveReviews": 15,
      "createdAt": "2025-09-22T14:30:00Z"
    }
  ]
}

Error Responses:

  • 401 Unauthorized: Authentication required/failed

  • 500 Internal Server Error: Server error

8. Get My Shops (Paginated)

Purpose: Retrieves user's shops with pagination

Endpoint: GET /api/v1/shops/my-shops-paged

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header
Type
Required
Description

Authorization

string

Yes

Bearer token for authentication

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

Response JSON Sample:

{
  "success": true,
  "message": "My shops retrieved successfully",
  "data": {
    "shops": [
      {
        "shopId": "550e8400-e29b-41d4-a716-446655440002",
        "shopName": "Tech Paradise",
        "status": "ACTIVE",
        "isApproved": true,
        "averageRating": 4.5,
        "totalRatings": 23
      }
    ],
    "currentPage": 0,
    "pageSize": 10,
    "totalElements": 3,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": true
  }
}

Error Responses:

  • 401 Unauthorized: Authentication required/failed

  • 500 Internal Server Error: Server error

9. Approve Shop

Purpose: Approves or rejects a shop (Admin only)

Endpoint: PATCH /api/v1/shops/{shopId}/approve-shop

Access Level: 🔒 Protected (Requires SUPER_ADMIN or STAFF_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

shopId

UUID

Yes

ID of the shop to approve/reject

Valid UUID format

Query Parameters:

Parameter
Type
Required
Description
Validation
Default

approve

boolean

Yes

Approval status

true or false

N/A

Response JSON Sample:

{
  "success": true,
  "message": "Shop approval status changed successfully",
  "data": {
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise",
    "isApproved": true,
    "approvedAt": "2025-09-22T15:45:00Z"
  }
}

Error Responses:

  • 401 Unauthorized: Authentication required/failed

  • 403 Forbidden: Insufficient permissions

  • 404 Not Found: Shop not found

  • 500 Internal Server Error: Server error

10. Get Shops by Category

Purpose: Retrieves all shops in a specific category

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

Access Level: 🌐 Public

Authentication: None

Path Parameters:

Parameter
Type
Required
Description
Validation

categoryId

UUID

Yes

ID of the category

Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Shops by category retrieved successfully",
  "data": [
    {
      "shopId": "550e8400-e29b-41d4-a716-446655440002",
      "shopName": "Tech Paradise",
      "categoryName": "Electronics",
      "averageRating": 4.5,
      "totalRatings": 23,
      "city": "Dar es Salaam",
      "logoUrl": "https://example.com/logos/tech-paradise.png"
    }
  ]
}

Error Responses:

  • 404 Not Found: Category not found

  • 500 Internal Server Error: Server error

11. Get Shops by Category (Paginated)

Purpose: Retrieves shops in a specific category with pagination

Endpoint: GET /api/v1/shops/category/{categoryId}/paged

Access Level: 🌐 Public

Authentication: None

Path Parameters:

Parameter
Type
Required
Description
Validation

categoryId

UUID

Yes

ID of the category

Valid UUID format

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

Response JSON Sample:

{
  "success": true,
  "message": "Shops by category retrieved successfully",
  "data": {
    "shops": [
      {
        "shopId": "550e8400-e29b-41d4-a716-446655440002",
        "shopName": "Tech Paradise",
        "categoryName": "Electronics",
        "averageRating": 4.5,
        "totalRatings": 23
      }
    ],
    "currentPage": 0,
    "pageSize": 10,
    "totalElements": 15,
    "totalPages": 2,
    "hasNext": true,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": false
  }
}

Error Responses:

  • 404 Not Found: Category not found

  • 500 Internal Server Error: Server error

12. Get Featured Shops

Purpose: Retrieves featured/random shops (up to 20)

Endpoint: GET /api/v1/shops/featured

Access Level: 🌐 Public

Authentication: None

Response JSON Sample:

{
  "success": true,
  "message": "Featured shops retrieved successfully",
  "data": [
    {
      "shopId": "550e8400-e29b-41d4-a716-446655440002",
      "shopName": "Tech Paradise",
      "categoryName": "Electronics",
      "averageRating": 4.5,
      "totalRatings": 23,
      "city": "Dar es Salaam",
      "logoUrl": "https://example.com/logos/tech-paradise.png"
    }
  ]
}

Error Responses:

  • 500 Internal Server Error: Server error

13. Get Featured Shops (Paginated)

Purpose: Retrieves featured/random shops with pagination

Endpoint: GET /api/v1/shops/featured-paged

Access Level: 🌐 Public

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

Response JSON Sample:

{
  "success": true,
  "message": "Featured shops retrieved successfully",
  "data": {
    "shops": [
      {
        "shopId": "550e8400-e29b-41d4-a716-446655440002",
        "shopName": "Tech Paradise",
        "categoryName": "Electronics",
        "averageRating": 4.5,
        "totalRatings": 23
      }
    ],
    "currentPage": 0,
    "pageSize": 10,
    "totalElements": 50,
    "totalPages": 5,
    "hasNext": true,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": false
  }
}

Error Responses:

  • 500 Internal Server Error: Server error

14. Get Shop Summary Stats

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

Endpoint: GET /api/v1/shops/{shopId}/summary-stats

Access Level: 🌐 Public

Authentication: None

Path Parameters:

Parameter
Type
Required
Description
Validation

shopId

UUID

Yes

ID of the shop

Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Shop summary stats retrieved successfully",
  "data": {
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise",
    "averageRating": 4.5,
    "totalRatings": 23,
    "ratingDistribution": {
      "1": 1,
      "2": 0,
      "3": 2,
      "4": 5,
      "5": 15
    },
    "totalReviews": 18,
    "activeReviews": 15,
    "hiddenReviews": 2,
    "flaggedReviews": 1,
    "userActivities": [
      {
        "userId": "550e8400-e29b-41d4-a716-446655440003",
        "userName": "Jane Smith",
        "reviewId": "550e8400-e29b-41d4-a716-446655440004",
        "reviewText": "Great service and products!",
        "reviewStatus": "ACTIVE",
        "reviewDate": "2025-09-22T10:30:00Z",
        "ratingId": "550e8400-e29b-41d4-a716-446655440005",
        "ratingValue": 5,
        "ratingDate": "2025-09-22T10:35:00Z",
        "hasReview": true,
        "hasRating": true
      }
    ]
  }
}

Response Fields:

Field
Description

shopId

ID of the shop

shopName

Name of the shop

averageRating

Average rating value

totalRatings

Total number of ratings

ratingDistribution

Count of ratings for each value (1-5)

totalReviews

Total number of reviews (all statuses)

activeReviews

Number of active reviews

hiddenReviews

Number of hidden reviews

flaggedReviews

Number of flagged reviews

userActivities

Combined user ratings and reviews activity

Error Responses:

  • 404 Not Found: Shop not found

  • 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)

  • Coordinates: Use decimal degrees format for latitude/longitude

Shop Status Types

  • 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 Types

  • PHYSICAL: Physical store only (brick-and-mortar)

  • ONLINE: Online store only (e-commerce)

  • HYBRID: Both physical and online presence

Verification Badge Types

  • 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)

Business Rules

  • Shop Names: Must be unique across the entire system

  • Shop Slugs: Auto-generated from shop names, must be unique

  • Auto-Approval: New shops are automatically approved but can be manually managed

  • Owner Permissions: Shop owners can only update their own shops

  • Admin Permissions: SUPER_ADMIN and STAFF_ADMIN can approve/reject shops

  • Featured Shops: Randomized selection from approved shops (up to 20 for non-paginated)

  • Soft Delete: Shops are marked as deleted but not physically removed

  • Location Data: Coordinates should be provided in decimal degrees format

PreviousShop CategoriesNextShop Ratings

Last updated