Reviews are customer-submitted ratings (1-5 stars) and text for a product. Submission is public-facing and goes through the product endpoint, where reviews are created **pending approval** (`approved: false`). The store owner moderates them via the moderation endpoints – listing pending reviews, approving/rejecting, or deleting. Only approved reviews appear on the storefront.

## List Reviews (Moderation)

```
GET /api/v1/reviews
```

Returns reviews for moderation, including pending ones. To submit a review, use `POST /api/v1/products/{idOrSlug}/reviews`.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 10 | Reviews per page (1-100) |
| `offset` | `number` | 0 | Reviews to skip |
| `approved` | `boolean` | – | Filter by approval status (omit for all, including pending) |
| `productId` | `string` | – | Filter to reviews of a single product (UUID) |
| `rating` | `number` | – | Filter by star rating (1-5) |

```bash
curl -H "Authorization: Bearer your_api_key" \
  "https://your-store.yns.store/api/v1/reviews?approved=false"
```

### Response (200)

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "productId": "0191abc0-0000-7000-8000-000000000200",
      "author": "Jane Doe",
      "email": "jane@example.com",
      "content": "Great quality, fits perfectly.",
      "rating": 5,
      "approved": false,
      "createdAt": "2024-06-15T10:30:00.000Z",
      "updatedAt": "2024-06-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 10
  }
}
```

---

## Get Review

```
GET /api/v1/reviews/{id}
```

Returns a single review by UUID.

```bash
curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/reviews/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "productId": "0191abc0-0000-7000-8000-000000000200",
  "author": "Jane Doe",
  "email": "jane@example.com",
  "content": "Great quality, fits perfectly.",
  "rating": 5,
  "approved": false,
  "createdAt": "2024-06-15T10:30:00.000Z",
  "updatedAt": "2024-06-15T10:30:00.000Z"
}
```

---

## Approve or Reject a Review

```
PATCH /api/v1/reviews/{id}
```

Sets a review's `approved` flag – `true` publishes it on the storefront, `false` unpublishes/rejects it.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `approved` | `boolean` | Yes | Set `true` to publish the review, `false` to unpublish/reject it |

```bash
curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"approved": true}' \
  https://your-store.yns.store/api/v1/reviews/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

Returns the updated review (same shape as Get Review).

---

## Delete Review

```
DELETE /api/v1/reviews/{id}
```

Hard-deletes the review by UUID.

```bash
curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/reviews/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

```json
{
  "ok": true,
  "deleted": 1
}
```

---

## List Product Reviews

```
GET /api/v1/products/{idOrSlug}/reviews
```

Returns **approved** reviews for a single product, with pagination and summary statistics (average rating and total review count). The product can be referenced by UUID or slug. When translations are enabled, pass `?lang=` to resolve a translated slug.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 10 | Reviews per page (1-100) |
| `offset` | `number` | 0 | Reviews to skip |

```bash
curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/products/classic-tee/reviews
```

### Response (200)

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "author": "Jane Doe",
      "content": "Great quality, fits perfectly.",
      "rating": 5,
      "createdAt": "2024-06-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 10
  },
  "summary": {
    "averageRating": 4.8,
    "reviewCount": 1
  }
}
```

---

## Create Product Review

```
POST /api/v1/products/{idOrSlug}/reviews
```

Submits a new review for a product. Reviews are created with `approved: false` and must be approved by the store owner (via `PATCH /api/v1/reviews/{id}`) before they appear publicly.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `author` | `string` | Yes | Reviewer display name (1-100 characters) |
| `email` | `string` | Yes | Reviewer email address |
| `content` | `string` | Yes | Review text (1-5000 characters) |
| `rating` | `number` | Yes | Star rating (1-5) |

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "author": "Jane Doe",
    "email": "jane@example.com",
    "content": "Great quality, fits perfectly.",
    "rating": 5
  }' \
  https://your-store.yns.store/api/v1/products/classic-tee/reviews
```

### Response (201)

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "author": "Jane Doe",
  "content": "Great quality, fits perfectly.",
  "rating": 5,
  "createdAt": "2024-06-15T10:30:00.000Z"
}
```