> ## 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, send replies, or generate 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/{reviewId}/reply` | `reviews:write` |

Session-authenticated calls must include `organizationId` in the query for reads or JSON body for replies. API keys already belong to one organization.

## 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 the marketplace allows a reply; 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 to a review

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

Reply to exactly one review by putting its OmniCommerce UUID in the URL. Send your own text, ask AI to draft a reply, or ask AI to generate and send. The JSON body contains writing options only.

| Field | Behavior |
| - | - |
| `reply` | Supplied text for this review, up to 500 characters. |
| `generateWithAi` | Defaults to `false`. Set `true` instead of supplying `reply` to generate a response for this review. Uses organization AI credits. |
| `submit` | Defaults to `true`: submit to the marketplace. Set `false` with AI generation to return a draft without posting. |
| `instructions` | Optional AI writing instructions, up to 2,000 characters. Requires `generateWithAi: true`. |

Send supplied text:

```json theme={null}
{
  "reply": "Thank you for your review!"
}
```

Generate a draft without posting:

```json theme={null}
{
  "generateWithAi": true,
  "submit": false,
  "instructions": "Keep the reply warm and concise."
}
```

To generate and send, use `generateWithAi: true` and `submit: true`. AI uses the buyer review, linked product, brand voice, and previous store replies. Organization AI usage must be recorded before a generated reply can be returned or submitted.

The response `data` contains `reviewId`, `success`, `submitted`, the reply text when available, and optional `model`, `error`, and `sellerCenterUrl`. It returns one result for the review in the URL.

**Check `submitted` to know whether a reply was confirmed by the marketplace.** A successful draft has `submitted: false`. A failed draft or submission has `success: false`. Generated text remains available if submission fails, so you can inspect the stored review state and reuse the text without generating it again. Do not blindly retry an unconfirmed submission.

Shopee and Lazada accept eligible review replies. TikTok, Shopify, WhatsApp, Amazon, Zalora, and eBay return their concrete capability limitation through the shared review service. Unsupported targets are never reported as submitted. This endpoint does not request reviews from Amazon buyers.

The separate public `draft-reply` endpoint has been removed. AI drafting in the workspace Reviews page remains available.

## SDK

```ts theme={null}
const inbox = await client.reviews.list({ priority: "unreplied" });
const review = inbox.data.reviews[0];

await client.reviews.reply({
  reviewId: review.id,
  reply: "Thank you for your review!",
});

const draft = await client.reviews.reply({
  reviewId: review.id,
  generateWithAi: true,
  submit: false,
  instructions: "Keep the reply warm and concise.",
});

await client.reviews.reply({
  reviewId: review.id,
  generateWithAi: true,
  submit: true,
});
```

```python theme={null}
inbox = client.reviews.list(priority="unreplied")
review = inbox["data"]["reviews"][0]

result = client.reviews.reply(
    review_id=review["id"],
    generate_with_ai=True,
    submit=False,
    instructions="Keep the reply warm and concise.",
)
```

New and changed reviews also arrive as [review webhooks](https://docs.omnicommerce.sg/webhooks/reviews.md).


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