> ## Documentation Index
> Fetch the complete documentation index at: https://twigz.arqqin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reviews Admin

> Administrative review moderation and management

## Overview

Reviews Admin API provides moderation tools for managing flagged reviews, processing review reports, viewing platform-wide review analytics, and maintaining content quality across the platform. All functions require admin authorization.

**Location:** `convex/admins/reviewsAdmin.ts`

***

## Get Flagged Reviews

Lists flagged reviews with pagination. Returns flag details, review content, customer info, reporter info, and store info.

<ParamField path="paginationOpts" type="PaginationOptions" required>
  Pagination options
</ParamField>

<ParamField path="status" type="string">
  Filter by flag status: `pending`, `reviewed`, `dismissed`, `action_taken`
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const flaggedReviews = await convex.query(api.admins.reviewsAdmin.getFlaggedReviews, {
    paginationOpts: { numItems: 20, cursor: null },
    status: "pending"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "page": [
      {
        "_id": "f123456789",
        "_creationTime": 1700000000000,
        "reason": "fake",
        "description": "Customer never ordered here",
        "status": "pending",
        "adminNotes": null,
        "reviewedBy": null,
        "reviewedAt": null,
        "review": {
          "_id": "r123456789",
          "rating": 1,
          "title": "Terrible",
          "comment": "Worst food ever",
          "isVisible": true,
          "flaggedCount": 2,
          "customer": { "_id": "c111", "name": "John" },
          "store": { "_id": "s111", "name": "Pizza Palace" }
        },
        "reporter": { "_id": "c222", "name": "Store Manager" }
      }
    ],
    "isDone": true,
    "continueCursor": null
  }
  ```
</ResponseExample>

***

## Process Review Flag

Takes action on a flagged review. Updates the flag status and optionally modifies or removes the review.

<ParamField path="flagId" type="Id<'reviewFlags'>" required>
  Flag ID to process
</ParamField>

<ParamField path="action" type="string" required>
  Action to take:

  * `dismiss` — Flag is dismissed, review stays visible
  * `hide_review` — Review is hidden (isVisible set to false), flag marked as action\_taken
  * `remove_review` — Review and all associated data (votes, flags) are permanently deleted
  * `warn_customer` — Flag marked as action\_taken (customer warning system is TODO)
</ParamField>

<ParamField path="adminNotes" type="string">
  Admin notes about the decision
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.admins.reviewsAdmin.processReviewFlag, {
    flagId: "f123456789",
    action: "hide_review",
    adminNotes: "Review contained inappropriate language"
  });
  ```
</CodeGroup>

***

## Get Review Statistics

Returns platform-wide review analytics. When no `timeRange` is specified, uses pre-computed all-time aggregate stats for fast reads. Time-filtered queries compute stats on the fly.

<ParamField path="timeRange" type="string">
  Filter period: `7d`, `30d`, `90d`, `1y`. Omit for all-time stats (fastest).
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const stats = await convex.query(api.admins.reviewsAdmin.getReviewStatistics, {
    timeRange: "30d"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "totalReviews": 1250,
    "averageRating": 4.3,
    "flaggedReviews": 15,
    "hiddenReviews": 5,
    "reviewsWithResponses": 800,
    "verifiedReviews": 1100,
    "topRatedStores": [
      {
        "storeId": "s123",
        "storeName": "Pizza Palace",
        "averageRating": 4.9,
        "reviewCount": 120
      }
    ],
    "ratingDistribution": {
      "rating1": 30,
      "rating2": 50,
      "rating3": 150,
      "rating4": 400,
      "rating5": 620
    }
  }
  ```
</ResponseExample>

<Note>
  Top rated stores require a minimum of 3 reviews to appear in the ranking. Up to 10 stores are returned.
</Note>

***

## Bulk Hide Reviews

Hides multiple reviews at once. Sets `isVisible` to false for each review and recalculates stats for all affected stores.

<ParamField path="reviewIds" type="Id<'storeReviews'>[]" required>
  Array of review IDs to hide
</ParamField>

<ParamField path="reason" type="string" required>
  Reason for bulk hiding
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await convex.mutation(api.admins.reviewsAdmin.bulkHideReviews, {
    reviewIds: ["r111", "r222", "r333"],
    reason: "Spam campaign detected"
  });
  // result: { hiddenCount: 3, errors: [] }
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "hiddenCount": 3,
    "errors": []
  }
  ```
</ResponseExample>

***

## Get Store Review Summary

Returns a detailed review summary for a specific store, including all reviews (visible and hidden), statistics, and the 10 most recent reviews with customer names.

<ParamField path="storeId" type="Id<'stores'>" required>
  Store ID to get summary for
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const summary = await convex.query(api.admins.reviewsAdmin.getStoreReviewSummary, {
    storeId: "s123456789"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "store": { "_id": "s123", "name": "Pizza Palace" },
    "totalReviews": 45,
    "averageRating": 4.5,
    "flaggedReviews": 2,
    "hiddenReviews": 1,
    "reviewsWithResponses": 30,
    "verifiedReviews": 40,
    "recentReviews": [
      {
        "_id": "r123",
        "_creationTime": 1700000000000,
        "rating": 5,
        "comment": "Amazing pizza!",
        "isVisible": true,
        "flaggedCount": 0,
        "customer": { "name": "Jane" }
      }
    ]
  }
  ```
</ResponseExample>

<Note>
  Unlike the customer-facing store reviews query, this admin view includes hidden reviews in the total count and statistics.
</Note>