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/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

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

POST /api/v1/reviews/actions

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

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

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

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

inbox = client.reviews.list(priority="unreplied")

New and changed reviews also arrive as review webhooks.

Get started

Guides

SDK

CLI

Webhooks

MCP

Authentication

List reviews

Reply

Draft a reply with AI

SDK

​Authentication

​List reviews

​Reply

​Draft a reply with AI

​SDK

Authentication

List reviews

Reply

Draft a reply with AI

SDK