Shop Review

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: ~~2025-09-23~~2026-05-19
Version: ~~v1.~~v2.0

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

Short Description: The Shop Review API allows users to write, manage, and retrieve reviews (text ~~reviews~~+ star rating) for shops. ~~Users can~~Supports create, update, ~~and~~delete, ~~delete~~listing ~~their~~with ~~reviews while viewing comprehensive review analytics~~pagination, and ~~filtering~~summary ~~by status.~~statistics.

Hints:

All ~~review~~endpoints use the prefix api/v1/e-commerce/shops/reviews/{shopId}

All operations require Bearer token authentication
~~Users can only have one~~One review per user per shop (— use PUT to update toan ~~change)~~existing one
Shop owners cannot review their own shops
~~Review~~reviewText ~~text~~and ratingValue are both optional fields, but at least one should be provided

ratingValue must be ~~10-~~1–5 if provided

reviewText must be 10–1000 characters if provided
~~Reviews~~isMyReview ~~have~~flag ~~status:~~is ~~ACTIVE,~~only ~~HIDDEN,~~populated ~~FLAGGED,~~when ~~UNDER_REVIEW~~the authenticated user is included in the response builder

Standard Response Format

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully"...",
  "action_time": "2025-09-23T10:2026-05-19T10: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"
}

Endpoints

1. Create Review (Feedback)

~~Purpose~~~~: Creates a new text review for a shop~~

Endpoint: POST {base_url}/api/v1/e-commerce/shops/reviews/{shopId}

Access Level: 🔒 Protected ~~(Requires Bearer Token)~~

~~Authentication~~~~: Bearer Token~~

Path Parameters:

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

Request ~~Headers~~Body:

~~Header~~Parameter	Type	Required	~~Description~~Validation
~~Authorization~~reviewText	string	~~Yes~~No	~~Bearer~~Min: ~~token~~10, ~~for~~Max: ~~authenticated~~1000 ~~user~~chars
~~Content-Type~~ratingValue	~~string~~integer	~~Yes~~No	~~application/json~~Min: 1, Max: 5

Request JSON Sample:

{
  "reviewText": "Amazing food and excellent service! The staff was very friendly and the atmosphere was perfect for a family dinner. Highly recommend the local dishes.",
  "ratingValue": 5
}

~~Request Body Parameters~~:

~~Parameter~~	~~Type~~	~~Required~~	~~Description~~	~~Validation~~
~~reviewText~~	~~string~~	~~Yes~~	~~Review content~~	~~Min: 10, Max: 1000 characters~~

~~Success~~ Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "ReviewFeedback createdsubmitted successfully",
  "action_time": "2025-09-23T10:2026-05-19T10:30:45",
  "data": {
    "reviewId": "review-123e4567-e89b-12d3-a456-426614174000",
    "shopId": "123e4567-456e7890-e89b-12d3-a456-426614174000"426614174001",
    "shopName": "Mama Lucy's Restaurant",
    "userId": "456e7890-789e0123-e89b-12d3-a456-426614174001"426614174002",
    "userName": "John Doe",
    "reviewText": "Amazing food and excellent service! The staff was very friendly and the atmosphere was perfect for a family dinner. Highly recommend the local dishes.",
    "ratingValue": 5,
    "status": "ACTIVE",
    "createdAt": "2025-09-23T10:2026-05-19T10:30:45",
    "updatedAt": "2025-09-23T10:2026-05-19T10:30:45",
    "isMyReview": false
  }
}

Error ~~Response Examples~~Responses:

~~Review~~

400: Already ~~Exists (400):~~

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "You have already reviewed this shop.shop, Useor updateshop toowner changereviewing yourown review.",shop


"action_time"401: "2025-09-23T10:30:45",Authentication "data"required

404: "You have already reviewed this shop. Use update to change your review." }
~~Shop Owner Cannot Review Own~~ Shop ~~(400):~~
not
```
{found
```


"success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Shop owners cannot review their own shops",
  "action_time": "2025-09-23T10:30:45",
  "data": "Shop owners cannot review their own shops"
}

2. Update Review (Feedback)

~~Purpose~~~~: Updates user's existing review for a shop~~

Endpoint: PUT {base_url}/api/v1/e-commerce/shops/reviews/{shopId}

Access Level: 🔒 Protected (Review Owner ~~Only)~~

~~Authentication~~~~: Bearer Token~~only)

Path Parameters:

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

Request ~~JSON~~Body ~~Sample~~:

(same

{as "reviewText":Create "Updated— review:all Stillfields amazing food but service could be improved. The local dishes are definitely worth trying and the prices are reasonable."
}

~~Request Body Parameters~~optional):

Parameter	Type	~~Required~~	~~Description~~	Validation
reviewText	string	~~Yes~~	~~Updated review content~~	Min: 10, Max: 1000 ~~characters~~chars
ratingValue	integer	Min: 1, Max: 5

~~Success~~ Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "ReviewFeedback updated successfully",
  "action_time": "2025-09-23T10:30:45"2026-05-19T11:15:30",
  "data": {
    "reviewId": "review-123e4567-e89b-12d3-a456-426614174000",
    "shopId": "123e4567-456e7890-e89b-12d3-a456-426614174000"426614174001",
    "shopName": "Mama Lucy's Restaurant",
    "userId": "456e7890-789e0123-e89b-12d3-a456-426614174001"426614174002",
    "userName": "John Doe",
    "reviewText": "Updated review: Still amazing foodfood. but service could be improved. The localLocal dishes are definitely worth trying and the prices are reasonable.it.",
    "ratingValue": 4,
    "status": "ACTIVE",
    "createdAt": "2025-09-23T10:2026-05-19T10:30:45",
    "updatedAt": "2025-09-23T11:2026-05-19T11:15:30",
    "isMyReview": false
  }
}

Error ~~Response Examples~~Responses:

~~Review~~

~~Not Found (404):~~

{
  "success"401: false,Authentication "httpStatus"required

404: "NOT_FOUND",
  "message": "Review not found.found Create(create aone reviewfirst)
first.",
  "action_time": "2025-09-23T10:30:45",
  "data": "Review not found. Create a review first."
}

3. Delete Review (Feedback)

~~Purpose~~~~: Soft deletes user's review for a shop~~

Endpoint: DELETE {base_url}/api/v1/e-commerce/shops/reviews/{shopId}

Access Level: 🔒 Protected (Review Owner ~~Only)~~

~~Authentication~~~~: Bearer Token~~only)

Path Parameters:

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

Soft-deletes the review. Deleted reviews no longer appear in listings or counts.

~~Success~~ Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "ReviewFeedback deleted successfully",
  "action_time": "2025-09-23T10:2026-05-19T10:30:45",
  "data": null
}

Error Responses:

401: Authentication required

404: Review not found

4. Get Active Reviews for Shop

~~Purpose~~~~: Retrieves all active reviews for a specific shop~~

Endpoint: GET {base_url}/api/v1/e-commerce/shops/reviews/{shopId}/active-reviews-by-shop

Access Level: 🔒 Protected (~~Requires~~auth ~~Authentication~~required to ~~show~~populate isMyReview flag)

Authentication: Bearer Token)

Path Parameters:

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

Returns all ACTIVE reviews. isMyReview is set to true for the authenticated user's own review.

~~Success~~ Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop reviewsReviews retrieved successfully",
  "action_time": "2025-09-23T10:2026-05-19T10:30:45",
  "data": [
    {
      "reviewId": "review-123e4567-e89b-12d3-a456-426614174000",
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "Mama Lucy's Restaurant",
      "userId": "456e7890-e89b-12d3-a456-426614174001",
      "userName": "John Doe",
      "reviewText": "Amazing food and excellent service!",
      "status": "ACTIVE",
      "createdAt": "2025-09-23T10:30:45",
      "updatedAt": "2025-09-23T10:30:45",
      "isMyReview": true
    },
    {
      "reviewId": "review-456e7890-e89b-12d3-a456-426614174001",
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "Mama Lucy's Restaurant",
      "userId": "789e0123-e89b-12d3-a456-426614174002",
      "userName": "JaneJohn Smith"Doe",
      "reviewText": "GreatAmazing local dishes, very authentic taste!food!",
      "ratingValue": 5,
      "status": "ACTIVE",
      "createdAt": "2025-09-22T15:20:30"2026-05-19T10:30:45",
      "updatedAt": "2025-09-22T15:20:30"2026-05-19T10:30:45",
      "isMyReview": falsetrue
    }
  ]
}

Error Responses:

401: Authentication required

404: Shop not found

5. Get Active Reviews for Shop (Paginated)

~~Purpose~~~~: Retrieves active reviews for a shop with pagination~~

Endpoint: GET {base_url}/api/v1/e-commerce/shops/reviews/{shopId}/paged

Access Level: 🔒 Protected ~~(Requires Authentication)~~

~~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~~Default	Description	~~Validation~~	~~Default~~
page	~~integer~~	No1	Page number (1-based)	~~Min: 1~~	1
size	~~integer~~10	No	~~Number of items~~Items per page	~~Min:~~(max: ~~1, Max: 100~~	10100)

~~Success~~ Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop reviewsReviews retrieved successfully",
  "action_time": "2025-09-23T10:2026-05-19T10:30:45",
  "data": {
    "reviews": [
      {
        "reviewId": "review-123e4567-e89b-12d3-a456-426614174000",
        "shopId": "123e4567-e89b-12d3-a456-426614174000",
        "shopName": "Mama Lucy's Restaurant",
        "userName": "John Doe",
        "reviewText": "Amazing food and excellent service!food!",
        "ratingValue": 5,
        "status": "ACTIVE",
        "createdAt": "2025-09-23T10:2026-05-19T10:30:45",
        "isMyReview": true
      }
    ],
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": false
  }
}

Error Responses:

401: Authentication required

404: Shop not found

6. Get My Review for Shop

~~Purpose~~~~: Retrieves authenticated user's review for a specific shop~~

Endpoint: GET {base_url}/api/v1/e-commerce/shops/reviews/{shopId}/my-review

Access Level: 🔒 Protected

~~(Authenticated~~

Returns ~~User~~the ~~Only)~~authenticated user's review for the shop, or null if they haven't reviewed it yet.

~~Authentication~~~~: Bearer Token~~

~~Path Parameters~~:

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

~~Success~~ Response JSON Sample (has review):

{
  "success": true,
  "httpStatus": "OK",
  "message": "Your reviewfeedback retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "reviewId": "review-123e4567-e89b-12d3-a456-426614174000",
    "shopId": "123e4567-456e7890-e89b-12d3-a456-426614174000"426614174001",
    "shopName": "Mama Lucy's Restaurant",
    "userId": "456e7890-789e0123-e89b-12d3-a456-426614174001"426614174002",
    "userName": "John Doe",
    "reviewText": "Amazing food and excellent service!food!",
    "ratingValue": 5,
    "status": "ACTIVE",
    "createdAt": "2025-09-23T10:2026-05-19T10:30:45",
    "updatedAt": "2025-09-23T10:2026-05-19T10:30:45",
    "isMyReview": false
  }
}

~~Success~~ Response ~~(No~~when ~~Review~~no ~~Found)~~review exists:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Your reviewfeedback retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": null
}

7. Get Shop Review Summary

~~Purpose~~~~: Retrieves comprehensive review statistics for a shop by status~~

Endpoint: GET {base_url}/api/v1/e-commerce/shops/reviews/{shopId}/summary-shop-reviewsummary

Access Level: 🌐 Public

~~(No~~

Returns ~~authentication~~aggregated ~~required)~~rating and review counts for a shop.

~~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 reviewfeedback summary retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-456e7890-e89b-12d3-a456-426614174000"426614174001",
    "shopName": "Mama Lucy's Restaurant",
    "totalReviews"averageRating": 4.5,
    "totalRatings": 25,
    "ratingDistribution": { "1": 1, "2": 2, "3": 5, "4": 7, "5": 10 },
    "totalReviews": 15,
    "activeReviews": 22,12,
    "hiddenReviews": 2,
    "flaggedReviews": 1
  }
}

~~Success Response Fields~~:

~~Field~~	~~Description~~
~~shopId~~	~~Unique identifier of the shop~~
~~shopName~~	~~Name of the shop~~
~~totalReviews~~	~~Total number of reviews (all statuses)~~
~~activeReviews~~	~~Number of active/visible reviews~~
~~hiddenReviews~~	~~Number of hidden reviews~~
~~flaggedReviews~~	~~Number of flagged reviews~~

DataQuick ModelsReference

Review StatusReviewStatus Enum

Value	Description
`ACTIVE`	~~Review~~Visible isin ~~visible~~public ~~and active~~listings
`HIDDEN`	~~Review is hidden~~Hidden from public view
`FLAGGED`	~~Review has been flagged~~Flagged for admin review
`UNDER_REVIEW`	~~Review is under~~Under admin review

ReviewResponse

Business Rules

Review Creation RulesFields

~~Users~~

~~must~~

~~authenticated~~

~~create~~

~~reviews~~

~~One~~

~~shop~~

~~(use~~

~~update~~

~~modify)~~

~~cannot~~

~~review~~

~~their~~

~~own~~

~~shops~~

~~Cannot review deleted shops~~

~~10-1000~~

~~characters~~

~~New~~

~~reviews~~

Review Update Rules

~~Only~~

~~can~~

~~review~~

~~Must~~

~~have~~

~~existing~~

~~review to update~~

~~Same validation rules apply as creation~~

~~Updates set new updatedAt timestamp~~

Review Deletion Rules

~~Only review owner can delete their review~~

~~Soft delete (sets isDeleted = true)~~

~~Deleted reviews don't appear in listings or counts~~

Review Status Rules

~~Only ACTIVE reviews appear in public listings~~

~~All statuses count in summary statistics~~

~~isMyReview flag shows~~

Error

~~Types~~

Field	Type	Description
reviewId	UUID	Unique review ~~per~~ID
shopId	UUID	Shop that was reviewed
shopName	string	Shop name
userId	UUID	Reviewer's user ~~per~~ID
userName	string	Reviewer's ~~Shop~~display ~~owners~~name
reviewText	string	Review text ~~must~~content
ratingValue	integer	Star ~~default~~rating to(1–5), ~~ACTIVE~~nullable
status	ReviewStatus	Current review ~~owner~~status
createdAt	LocalDateTime	Creation timestamp
updatedAt	LocalDateTime	Last update ~~their~~timestamp
isMyReview	boolean	True if ~~review~~this ~~belongs~~is tothe current ~~user~~user's review

Standard Error Codes

~~BAD_REQUEST~~

~~UNAUTHORIZED~~

~~token~~

~~NOT_FOUND~~

~~user~~

~~not~~

~~authenticated~~

~~UNPROCESSABLE_ENTITY~~

Validation

~~Error~~

Code	Meaning
`400`	Business ~~logic~~rule ~~violations,~~violation ~~already~~(duplicate ~~exists~~review, owner self-review)
`401`	Authentication ~~Invalid/missing~~required
`404`	Shop ~~Shop/~~or review not ~~found,~~found
`422`	Field ~~Validation~~validation errors

~~Example~~

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "reviewText": "Review must be between 10 and 1000 characters"
  }
}