List Product Reviews (v1)

Method & Path

GET /api/v1/workspace/:workspaceId/storefront/product-reviews

Actual backend path: /v1/workspace/:workspaceId/storefront/product-reviews

Description

Lists product reviews for the workspace storefront. Supports filtering by product and by moderation/visibility state.

Authentication

Required: Bearer JWT.

Permissions: store.products.manage

Personas: Workspace Owner, Staff (role-based) with product management permission.

Headers

Header	Required	Description
Authorization	Yes	Bearer <token>
X-Staff-Id	If staff	Staff member id when acting as staff

Query Parameters

Parameter	Type	Required	Description
productId	string	No	Limit to reviews for a single product
visibility	string	No	all (default), customer_visible (status visible), customer_hidden (status pending or hidden)
status	string	No	all (default), pending, visible, hidden. If set (not all), overrides visibility.
limit	number	No	1–200, default 50
offset	number	No	Pagination offset

Response 200 OK

{
  "reviews": [
    {
      "id": "…",
      "productId": "…",
      "productName": "Product name",
      "rating": 5,
      "comment": "Great",
      "authorName": "Sara",
      "status": "pending",
      "createdAt": "2026-04-05T10:00:00.000Z",
      "updatedAt": "2026-04-05T10:00:00.000Z"
    }
  ],
  "total": 1
}

Common Errors

• 401 Unauthorized: Missing or invalid token
• 403 Forbidden: Missing store.products.manage
• 400 Bad Request: Invalid query parameters