Reviews

Base path: /api/reviews, /api/venues/{venue}/reviews

Users can leave a star rating and comment for a venue after a completed booking.

Endpoints

GET /api/venues/{venue}/reviews

Get all approved reviews for a venue.

Auth: Not required (send a Bearer token to also receive can_review and my_review)

Path parameter: venue — venue ID (integer) or slug (e.g. kabya-futsal-1l5eQ)

Response 200:

{
  "average_rating": 4.3,
  "reviews_count": 1,
  "can_review": false,
  "my_review": null,
  "reviews": [
    {
      "id": 3,
      "rating": 5,
      "comment": "Excellent courts and great staff!",
      "is_approved": true,
      "user": {
        "id": 12,
        "name": "Rahul K.",
        "avatar": "https://..."
      },
      "images": [
        { "id": 1, "url": "https://..." }
      ],
      "replies": [
        {
          "id": 1,
          "reply": "Thank you! See you again.",
          "user": { "id": 5, "name": "Venue Manager" },
          "created_at": "2025-06-10 11:00:00"
        }
      ],
      "created_at": "2025-06-09 15:30:00"
    }
  ]
}

POST /api/venues/{venue}/reviews [Auth required]

Submit a review from the venue page. This is the app endpoint.

Path parameter: venue — venue ID or slug

Auth: Bearer token

Request body:

{
  "rating": 5,
  "comment": "Excellent courts and great staff!"
}

booking_id is optional. If omitted, the API attaches the user's latest booking at that venue when one exists.

POST /api/reviews [Auth required]

Same create action with ids in the body (legacy).

Request body:

{
  "venue_id": 1,
  "booking_id": 42,
  "rating": 5,
  "comment": "Excellent courts and great staff!",
  "images": ["base64-or-file-upload"]
}

Field	Type	Required	Description
`venue_id`	integer	Yes on `/api/reviews`; ignored on `/venues/{venue}/reviews`	Venue being reviewed
`booking_id`	integer	No	Booking to link; auto-picked when omitted
`rating`	number	Yes	1–5 stars (app may send `5.0`)
`comment`	string	No	Review text
`images`	array	No	Optional photo uploads

Response 201:

{
  "data": {
    "id": 5,
    "rating": 5,
    "comment": "Excellent courts and great staff!",
    "is_approved": false,
    "user": { ... },
    "images": [],
    "replies": [],
    "created_at": "2025-06-16 10:00:00"
  }
}

App-submitted reviews are visible immediately (is_approved: true). Venue owners/managers can still approve older pending reviews. One review per user per venue.

GET /api/admin/reviews [Auth required]

List reviews for venues the current tenant user can access (pending and approved).

Auth: venue_owner or manager

Query: is_approved — optional boolean filter

PATCH /api/admin/reviews/{review}/approve [Auth required]

Approve a review. Only allowed for the venue's owner or manager.

Auth: venue_owner or manager (scoped to that venue)

ReviewResource — Field Reference

Field	Type	Notes
`id`	integer
`rating`	integer	1 to 5
`comment`	string or null
`is_approved`	boolean	Only approved reviews show publicly
`user`	object	Reviewer's public info
`images`	array	Array of `{ id, url }`
`replies`	array	Venue staff replies
`created_at`	datetime string

Tips for Mobile Devs

List: GET /api/venues/{slug}/reviews — use the same slug as venue detail.
Submit: POST /api/venues/{slug}/reviews with { "rating": 5, "comment": "..." } and a Bearer token.
Show average_rating and reviews_count on venue cards (VenueResource).
Hide the review form when can_review is false (already reviewed or guest).