Skip to main content

​
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.
​
paginationOpts
PaginationOptions
required
Pagination options
​
status
string
Filter by flag status: pending, reviewed, dismissed, action_taken
const flaggedReviews = await convex.query(api.admins.reviewsAdmin.getFlaggedReviews, {
  paginationOpts: { numItems: 20, cursor: null },
  status: "pending"
});

{
  "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
}

​
Process Review Flag

Takes action on a flagged review. Updates the flag status and optionally modifies or removes the review.
​
flagId
Id<'reviewFlags'>
required
Flag ID to process
​
action
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)
​
adminNotes
string
Admin notes about the decision
await convex.mutation(api.admins.reviewsAdmin.processReviewFlag, {
  flagId: "f123456789",
  action: "hide_review",
  adminNotes: "Review contained inappropriate language"
});

​
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.
​
timeRange
string
Filter period: 7d, 30d, 90d, 1y. Omit for all-time stats (fastest).
const stats = await convex.query(api.admins.reviewsAdmin.getReviewStatistics, {
  timeRange: "30d"
});

{
  "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
  }
}
Top rated stores require a minimum of 3 reviews to appear in the ranking. Up to 10 stores are returned.

​
Bulk Hide Reviews

Hides multiple reviews at once. Sets isVisible to false for each review and recalculates stats for all affected stores.
​
reviewIds
Id<'storeReviews'>[]
required
Array of review IDs to hide
​
reason
string
required
Reason for bulk hiding
const result = await convex.mutation(api.admins.reviewsAdmin.bulkHideReviews, {
  reviewIds: ["r111", "r222", "r333"],
  reason: "Spam campaign detected"
});
// result: { hiddenCount: 3, errors: [] }

{
  "hiddenCount": 3,
  "errors": []
}

​
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.
​
storeId
Id<'stores'>
required
Store ID to get summary for
const summary = await convex.query(api.admins.reviewsAdmin.getStoreReviewSummary, {
  storeId: "s123456789"
});

{
  "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" }
    }
  ]
}
Unlike the customer-facing store reviews query, this admin view includes hidden reviews in the total count and statistics.