> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shopi.lk/llms.txt
> Use this file to discover all available pages before exploring further.

# Reviews

> Fetch and submit product reviews

## `shop.reviews.list(productId, limit?)`

Returns approved reviews for a product, ordered by newest first.

```typescript theme={null}
const reviews = await shop.reviews.list('product-uuid-here', 10);
```

### Parameters

| Param       | Type     | Default | Description                     |
| ----------- | -------- | ------- | ------------------------------- |
| `productId` | `string` | —       | The product's UUID              |
| `limit`     | `number` | `50`    | Max reviews to return (max 100) |

### Response

```typescript theme={null}
Array<{
  id: string;
  product_id: string;
  rating: number;            // 1–5
  review_text: string | null;
  image_url: string | null;
  is_verified_purchase: boolean;
  created_at: string;
}>
```

### Example — Review list with star rating

```typescript theme={null}
const reviews = await shop.reviews.list(product.id, 10);

const avgRating = reviews.reduce((sum, r) => sum + r.rating, 0) / reviews.length;
ratingAvg.textContent = avgRating.toFixed(1);

reviews.forEach(review => {
  reviewList.innerHTML += `
    <div class="review">
      <div class="stars">${'★'.repeat(review.rating)}${'☆'.repeat(5 - review.rating)}</div>
      <p>${review.review_text ?? ''}</p>
      ${review.is_verified_purchase ? '<span class="verified">Verified Purchase</span>' : ''}
      <time>${new Date(review.created_at).toLocaleDateString()}</time>
    </div>
  `;
});
```

***

## `shop.reviews.submit(params)`

Submits a new review for a product. Reviews require **seller approval** before appearing publicly.

```typescript theme={null}
const result = await shop.reviews.submit({
  product_id: 'product-uuid-here',
  rating: 5,
  review_text: 'Amazing quality!',
  customer_name: 'Jane Doe',
  customer_email: 'jane@example.com',
});
```

### Parameters

| Param            | Type     | Required | Description                        |
| ---------------- | -------- | -------- | ---------------------------------- |
| `product_id`     | `string` | ✅        | UUID of the product being reviewed |
| `rating`         | `number` | ✅        | Integer between 1 and 5            |
| `review_text`    | `string` | ❌        | Written review                     |
| `customer_name`  | `string` | ❌        | Reviewer's name                    |
| `customer_email` | `string` | ❌        | Reviewer's email                   |
| `image_url`      | `string` | ❌        | URL of an attached image           |

### Response

```typescript theme={null}
{ id: string }
```

### Example — Review submission form

```typescript theme={null}
reviewForm.addEventListener('submit', async (e) => {
  e.preventDefault();
  submitBtn.disabled = true;

  try {
    await shop.reviews.submit({
      product_id: product.id,
      rating: parseInt(ratingInput.value),
      review_text: reviewTextarea.value,
      customer_name: nameInput.value,
      customer_email: emailInput.value,
    });

    successMsg.textContent = 'Thank you! Your review will appear after approval.';
    reviewForm.reset();
  } catch (error) {
    errorMsg.textContent = 'Failed to submit review. Please try again.';
  } finally {
    submitBtn.disabled = false;
  }
});
```

<Warning>
  Submitted reviews are not immediately visible. They require manual approval from the shop owner in their seller dashboard.
</Warning>