Reviews API

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

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

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:

{
  "reply": "Thank you for your review!"
}

Generate a draft without posting:

{
  "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

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,
});

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.

Get started

Guides

SDK

CLI

Webhooks

MCP

Authentication

List reviews

Reply to a review

SDK

​Authentication

​List reviews

​Reply to a review

​SDK

Authentication

List reviews

Reply to a review

SDK