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

# Reviews API

> Read marketplace product reviews, reply to buyers, and draft replies with AI.

Build a review inbox or show ratings next to your products. The endpoints read the same reviews as the workspace Reviews page, synced from connected marketplaces. Buyer names and the raw marketplace payload are never returned.

## Authentication

| Endpoint | Required scope |
| - | - |
| `GET /api/v1/reviews` | `reviews:read` |
| `GET /api/v1/reviews/{reviewId}` | `reviews:read` |
| `POST /api/v1/reviews/actions` | `reviews:write` |
| `POST /api/v1/reviews/{reviewId}/draft-reply` | `reviews:write` |

Session-authenticated calls must include `organizationId` in the query (GET) or JSON body (writes).

## List reviews

```http theme={null}
GET /api/v1/reviews?priority=unreplied&marketplace=shopee
```

| Parameter | Description |
| - | - |
| `q` | Search the comment, product name or SKU, marketplace item id, and review id. |
| `marketplace` | One marketplace, for example `shopee`. |
| `status` | `open`, `replied`, `hidden`, `handoff`, `solicited`, or `ineligible`. |
| `priority` | `unreplied`: open reviews that accept a reply. `negative`: rating of 3 or lower. |
| `store` | Comma-separated store ids from `GET /api/v1/marketplaces/connected`. |
| `productId` | A product or variant UUID. Includes reviews of the whole product family. |
| `sortBy` | Comma-separated: `reviewed_desc` (default), `reviewed_asc`, `rating_desc`, `rating_asc`, and more. |
| `limit` | Page size. Default `50`, max `100`. |
| `offset` | Zero-based offset. Use `data.nextOffset` to page forward; it is null on the last page. |

Unknown values return `400` instead of being ignored.

Each review includes `rating`, `comment`, `sellerReply`, the linked product (`productId`, `productName`, `productSku`, `productThumbnailUrl`), the store, and `marketplaceListingUrl`. `replyRestriction` is `null` when a reply will be accepted; otherwise it says why not, for example `This review already has a seller reply.` Use it to enable or explain a disabled reply button.

## Reply

```http theme={null}
POST /api/v1/reviews/actions
```

```json theme={null}
{
  "action": "review.reply",
  "targets": [
    { "reviewId": "1b6f…", "reply": "Thank you for the photos!" },
    { "reviewId": "7c02…" }
  ],
  "reply": "Thanks for shopping with us."
}
```

Send up to 50 targets. A target's own `reply` overrides the shared `reply`. Replies are limited to 500 characters. The marketplace call runs during the request, and each target succeeds or fails on its own:

```json theme={null}
{
  "ok": false,
  "status": "failed",
  "data": {
    "succeededCount": 1,
    "failedCount": 1,
    "results": [
      { "reviewId": "1b6f…", "success": true },
      {
        "reviewId": "7c02…",
        "success": false,
        "error": "This review already has a seller reply."
      }
    ]
  }
}
```

When a marketplace API cannot post the reply, the result includes `sellerCenterUrl` so the seller can finish there.

For Amazon, send `"action": "review.solicit"` with the ids of `kind: "solicitation"` rows to request a review for those orders.

## Draft a reply with AI

```http theme={null}
POST /api/v1/reviews/{reviewId}/draft-reply
```

Returns `{ "reply": "…", "model": "…" }` written from the review, the product, recent replies, and the organization's brand kit. Nothing is posted. Show the draft for editing, then send it with `POST /api/v1/reviews/actions`. Drafts use AI credits and are rate limited per organization.

## SDK

```ts theme={null}
const inbox = await client.reviews.list({ priority: "unreplied" });
const review = inbox.data.reviews[0];
const draft = await client.reviews.draftReply({ reviewId: review.id });
await client.reviews.actions({
  action: "review.reply",
  targets: [{ reviewId: review.id, reply: draft.data.reply }],
});
```

```python theme={null}
inbox = client.reviews.list(priority="unreplied")
```

New and changed reviews also arrive as [review webhooks](/webhooks/reviews).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.