TWIGZ Backend API Documentation

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.

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Reviews Admin

Overview

Get Flagged Reviews

Process Review Flag

Get Review Statistics

Bulk Hide Reviews

Get Store Review Summary

​Overview

​Get Flagged Reviews

​Process Review Flag

​Get Review Statistics

​Bulk Hide Reviews

​Get Store Review Summary

Overview

Get Flagged Reviews

Process Review Flag

Get Review Statistics

Bulk Hide Reviews

Get Store Review Summary