TWIGZ Backend API Documentation

Overview

Store Reviews API provides comprehensive review and rating functionality including customer reviews, store responses, helpfulness voting, review flagging, and review management. Location: convex/stores/reviews.ts

Verified Purchase Logic

Reviews do not require a verified purchase. Any authenticated customer can leave a review on any store. The isVerifiedPurchase flag is set automatically:

If orderId is provided: the flag is set to true (order must exist, belong to the customer, and be from the target store)
If orderId is omitted: the system checks if the customer has any delivered order from the store. If yes, isVerifiedPurchase is true; otherwise false

Reviews without a verified purchase are still created and visible — they simply lack the verified badge.

Add Review

Creates a new review for a store. Requires authentication. One review per order per customer (when orderId is provided).

storeId

Id<'stores'>

required

Store ID to review

orderId

Id<'orders'>

Optional order ID to link the review to a specific order. If provided, automatically sets isVerifiedPurchase to true.

rating

number

required

Rating from 1-5 stars

title

string

Review title (at least one of title or comment is required)

comment

string

Review comment (at least one of title or comment is required)

photoIds

Id<'_storage'>[]

Array of storage IDs for review photos

const review = await convex.mutation(api.stores.reviews.addReview, {
  storeId: "j123456789",
  orderId: "o123456789", // optional
  rating: 5,
  title: "Excellent food!",
  comment: "The pizza was amazing and delivery was fast. Highly recommended!",
  photoIds: ["s123456789"]
});

{
  "reviewId": "r123456789",
  "message": "Review added successfully"
}

Update Review

Updates an existing review. Only the review author can update their own review.

reviewId

Id<'storeReviews'>

required

Review ID to update

rating

number

Updated rating (1-5)

title

string

Updated title

comment

string

Updated comment

photoIds

Id<'_storage'>[]

Updated photo IDs

await convex.mutation(api.stores.reviews.updateReview, {
  reviewId: "r123456789",
  rating: 4,
  comment: "Updated: Still great food, but service was slower this time."
});

Delete Review

Deletes a review and all associated data (helpful votes, flags). Only the review author can delete their own review.

reviewId

Id<'storeReviews'>

required

Review ID to delete

await convex.mutation(api.stores.reviews.deleteReview, {
  reviewId: "r123456789"
});

Get Store Reviews

Lists reviews for a store with pagination, sorting, and filtering. Only visible reviews are returned. Does not require authentication, but authenticated users see their own helpfulness votes.

storeId

Id<'stores'>

required

Store ID

paginationOpts

PaginationOptions

required

Pagination options

sortBy

string

Sort order: newest, oldest, highest_rating, lowest_rating, most_helpful

ratingFilter

number

Filter by specific rating (1-5)

verifiedOnly

boolean

Show only verified purchase reviews

const reviews = await convex.query(api.stores.reviews.getStoreReviews, {
  storeId: "j123456789",
  paginationOpts: { numItems: 10, cursor: null },
  sortBy: "newest",
  verifiedOnly: true
});

{
  "page": [
    {
      "_id": "r123456789",
      "_creationTime": 1700000000000,
      "rating": 5,
      "title": "Excellent food!",
      "comment": "The pizza was amazing.",
      "photoUrls": ["https://..."],
      "isVerifiedPurchase": true,
      "helpfulCount": 3,
      "notHelpfulCount": 0,
      "storeResponse": {
        "comment": "Thank you!",
        "respondedAt": 1700001000000
      },
      "customer": {
        "_id": "c123456789",
        "name": "Jane"
      },
      "userVote": true
    }
  ],
  "isDone": false,
  "continueCursor": "cursor123"
}

Get Store Review Stats

Returns denormalized review statistics for a store. Fast query — reads pre-computed stats from the store document.

storeId

Id<'stores'>

required

Store ID

const stats = await convex.query(api.stores.reviews.getStoreReviewStats, {
  storeId: "j123456789"
});

Get Review

Fetches a single review by ID with full details including customer info, store info, photo URLs, and current user’s permissions and vote.

reviewId

Id<'storeReviews'>

required

Review ID

const review = await convex.query(api.stores.reviews.getReview, {
  reviewId: "r123456789"
});
// response includes: canEdit, canDelete, userVote

Get Customer Reviews

Lists all reviews written by the authenticated customer with pagination. Includes store info and store responses.

paginationOpts

PaginationOptions

required

Pagination options

const myReviews = await convex.query(api.stores.reviews.getCustomerReviews, {
  paginationOpts: { numItems: 10, cursor: null }
});

Add Store Response

Allows a store owner to respond to a review. One response per review.

reviewId

Id<'storeReviews'>

required

Review ID to respond to

comment

string

required

Store response comment

await convex.mutation(api.stores.reviews.addStoreResponse, {
  reviewId: "r123456789",
  comment: "Thank you for your wonderful review! We're glad you enjoyed our pizza."
});

Update Store Response

Allows a store owner to edit their existing response.

reviewId

Id<'storeReviews'>

required

Review ID with the response to update

comment

string

required

Updated response comment

await convex.mutation(api.stores.reviews.updateStoreResponse, {
  reviewId: "r123456789",
  comment: "Updated: Thank you! We've improved our delivery times based on your feedback."
});

Vote on Review

Vote on whether a review is helpful or not. Customers cannot vote on their own reviews. One vote per customer per review (can be changed).

reviewId

Id<'storeReviews'>

required

Review ID to vote on

isHelpful

boolean

required

true for helpful, false for not helpful

await convex.mutation(api.stores.reviews.voteOnReview, {
  reviewId: "r123456789",
  isHelpful: true
});

Flag Review

Report a review for moderation. One flag per customer per review. Creates a pending flag for admin review and sends an admin notification (high priority for offensive/fake reasons).

reviewId

Id<'storeReviews'>

required

Review ID to flag

reason

string

required

Reason for flagging: spam, inappropriate, fake, offensive, irrelevant, other

description

string

Additional details about the flag

await convex.mutation(api.stores.reviews.flagReview, {
  reviewId: "r123456789",
  reason: "fake",
  description: "This customer never ordered from our store"
});

Reviews include photo support, verified purchase indicators, helpfulness voting, store owner responses, and a full flagging/moderation pipeline.

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Store Reviews

Overview

Verified Purchase Logic

Add Review

Update Review

Delete Review

Get Store Reviews

Get Store Review Stats

Get Review

Get Customer Reviews

Add Store Response

Update Store Response

Vote on Review

Flag Review

​Overview

​Verified Purchase Logic

​Add Review

​Update Review

​Delete Review

​Get Store Reviews

​Get Store Review Stats

​Get Review

​Get Customer Reviews

​Add Store Response

​Update Store Response

​Vote on Review

​Flag Review

Overview

Verified Purchase Logic

Add Review

Update Review

Delete Review

Get Store Reviews

Get Store Review Stats

Get Review

Get Customer Reviews

Add Store Response

Update Store Response

Vote on Review

Flag Review