API reference

Reviews

Management API: GET /sites/{id}/reviews, POST /sites/{id}/reviews, GET /sites/{id}/reviews/settings, …

Base URL https://app.kanorio.com/api/v1Errors Pagination

List reviews

GET/sites/{id}/reviews

betastore:viewdefault (120/minute per token)

List reviews for a website, newest first. Filter by targetKind, targetId, status or source. Errors: FORBIDDEN.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
targetKind"PRODUCT" | "SERVICE" · query
What the review is about: a product or a bookable service.
targetIdstring · query
Id of the product or service.
status"PENDING" | "APPROVED" | "REJECTED" · query
source"BUYER" | "IMPORTED" · query
limitinteger · query
Maximum number of items to return, 1–100. Defaults to 20.
cursorstring · query
Opaque cursor from the previous page's nextCursor. Omit for the first page.

Response 200

dataobject[]required
data[].idstringrequired
data[].targetKind"PRODUCT" | "SERVICE"required
What the review is about: a product or a bookable service.
data[].targetIdstringrequired
Id of the product or service.
data[].targetTitlestring | nullrequired
Display name of the target when it still exists.
data[].status"PENDING" | "APPROVED" | "REJECTED"required
data[].source"BUYER" | "IMPORTED"required
BUYER reviews are tied to a paid order line or completed booking; IMPORTED ones were added by the store owner and are never shown as verified.
data[].authorNamestringrequired
data[].ratingintegerrequired
data[].contentstring | nullrequired
data[].replyobject | nullrequired
Store owner's public reply, if any.
data[].reply.bodystringrequired
data[].reply.repliedAtstringrequired
data[].reply.repliedBystring | nullrequired
data[].reviewDatestring | nullrequired
Original review date for imported reviews (ISO).
data[].publishedAtstring | nullrequired
When the review became public (ISO); null while pending or rejected.
data[].createdAtstringrequired
hasMorebooleanrequired
True when another page exists; pass nextCursor to fetch it.
nextCursorstring | nullrequired
Cursor for the next page, or null on the last page.

Errors

FORBIDDEN 403

MCP tool reviews_list

curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/reviews" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

Response

{
  "data": [
    {
      "id": "rev_1",
      "targetKind": "PRODUCT",
      "targetId": "prod_example01",
      "targetTitle": "Strawberry Birthday Cake",
      "status": "PENDING",
      "source": "BUYER",
      "authorName": "Avery",
      "rating": 5,
      "content": "Arrived on time and tasted fresh.",
      "reply": null,
      "reviewDate": null,
      "publishedAt": null,
      "createdAt": "2026-10-06T08:00:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Import reviews

POST/sites/{id}/reviews

betacommerce:managedefault (120/minute per token)

Add a review collected elsewhere (another marketplace, a paper form). It is published immediately, marked IMPORTED and never shown as a verified purchase. Errors: FORBIDDEN, VALIDATION, TARGET_NOT_FOUND.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.

Request body

targetKind"PRODUCT" | "SERVICE"required
What the review is about: a product or a bookable service.
targetIdstringrequired
Id of the product or service.
authorNamestringrequired
ratingintegerrequired
contentstring | null
reviewDatestring | null
When the review was originally written (ISO).

Response 200

idstringrequired
targetKind"PRODUCT" | "SERVICE"required
What the review is about: a product or a bookable service.
targetIdstringrequired
Id of the product or service.
targetTitlestring | nullrequired
Display name of the target when it still exists.
status"PENDING" | "APPROVED" | "REJECTED"required
source"BUYER" | "IMPORTED"required
BUYER reviews are tied to a paid order line or completed booking; IMPORTED ones were added by the store owner and are never shown as verified.
authorNamestringrequired
ratingintegerrequired
contentstring | nullrequired
replyobject | nullrequired
Store owner's public reply, if any.
reply.bodystringrequired
reply.repliedAtstringrequired
reply.repliedBystring | nullrequired
reviewDatestring | nullrequired
Original review date for imported reviews (ISO).
publishedAtstring | nullrequired
When the review became public (ISO); null while pending or rejected.
createdAtstringrequired

Errors

FORBIDDEN 403
VALIDATION 400
TARGET_NOT_FOUND 404

MCP tool reviews_import

curl -X POST "https://app.kanorio.com/api/v1/sites/{id}/reviews" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targetKind":"PRODUCT","targetId":"prod_example01","authorName":"Jordan","rating":4,"content":"Great crust.","reviewDate":"2026-09-01T00:00:00.000Z"}'

Response

{
  "id": "rev_2",
  "targetKind": "PRODUCT",
  "targetId": "prod_example01",
  "targetTitle": "Strawberry Birthday Cake",
  "status": "APPROVED",
  "source": "IMPORTED",
  "authorName": "Jordan",
  "rating": 4,
  "content": "Great crust.",
  "reply": null,
  "reviewDate": "2026-09-01T00:00:00.000Z",
  "publishedAt": "2026-10-28T09:00:00.000Z",
  "createdAt": "2026-10-06T08:00:00.000Z"
}

Retrieve settings

GET/sites/{id}/reviews/settings

betastore:viewdefault (120/minute per token)

Read a product's or service's review settings and current rating summary: whether reviews are enabled, when the rating is shown, any historical rating, and pending count. Errors: FORBIDDEN, TARGET_NOT_FOUND.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
targetKind"PRODUCT" | "SERVICE" · queryrequired
What the review is about: a product or a bookable service.
targetIdstring · queryrequired
Id of the product or service.

Response 200

targetKind"PRODUCT" | "SERVICE"required
What the review is about: a product or a bookable service.
targetIdstringrequired
Id of the product or service.
enabledbooleanrequired
Whether buyers can submit new reviews for this target.
visibility"always" | "never" | "threshold_3" | "threshold_10" | "threshold_30"required
When the rating is shown publicly: always, never, or once the review count reaches 3, 10 or 30.
historicalRatingnumber | nullrequired
Average rating carried over from another platform; blended into the public rating.
historicalCountintegerrequired
How many reviews the historical rating represents.
aggregateRatingnumber | nullrequired
Current blended average of approved reviews plus historical rating.
aggregateCountintegerrequired
Approved reviews plus historical count.
pendingCountintegerrequired
Reviews waiting for moderation.

Errors

FORBIDDEN 403
TARGET_NOT_FOUND 404

MCP tool reviews_settings_get

curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/reviews/settings" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

Response

{
  "targetKind": "PRODUCT",
  "targetId": "prod_example01",
  "enabled": true,
  "visibility": "threshold_10",
  "historicalRating": null,
  "historicalCount": 0,
  "aggregateRating": 5,
  "aggregateCount": 1,
  "pendingCount": 0
}

Update settings

PATCH/sites/{id}/reviews/settings

betacommerce:managedefault (120/minute per token)

Update a product's or service's review settings: enable or disable new reviews, choose when the rating is shown, or set a historical rating carried over from another platform. Omitted fields stay unchanged. Errors: FORBIDDEN, VALIDATION, TARGET_NOT_FOUND.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.

Request body

targetKind"PRODUCT" | "SERVICE"required
What the review is about: a product or a bookable service.
targetIdstringrequired
Id of the product or service.
enabledboolean
visibility"always" | "never" | "threshold_3" | "threshold_10" | "threshold_30"
historicalRatingnumber | null
Average rating from another platform; null clears it.
historicalCountinteger
How many reviews that historical rating represents.

Response 200

targetKind"PRODUCT" | "SERVICE"required
What the review is about: a product or a bookable service.
targetIdstringrequired
Id of the product or service.
enabledbooleanrequired
Whether buyers can submit new reviews for this target.
visibility"always" | "never" | "threshold_3" | "threshold_10" | "threshold_30"required
When the rating is shown publicly: always, never, or once the review count reaches 3, 10 or 30.
historicalRatingnumber | nullrequired
Average rating carried over from another platform; blended into the public rating.
historicalCountintegerrequired
How many reviews the historical rating represents.
aggregateRatingnumber | nullrequired
Current blended average of approved reviews plus historical rating.
aggregateCountintegerrequired
Approved reviews plus historical count.
pendingCountintegerrequired
Reviews waiting for moderation.

Errors

FORBIDDEN 403
VALIDATION 400
TARGET_NOT_FOUND 404

MCP tool reviews_settings_update

curl -X PATCH "https://app.kanorio.com/api/v1/sites/{id}/reviews/settings" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targetKind":"PRODUCT","targetId":"prod_example01","visibility":"threshold_3","historicalRating":4.8,"historicalCount":25}'

Response

{
  "targetKind": "PRODUCT",
  "targetId": "prod_example01",
  "enabled": true,
  "visibility": "threshold_3",
  "historicalRating": 4.8,
  "historicalCount": 25,
  "aggregateRating": 4.81,
  "aggregateCount": 26,
  "pendingCount": 0
}

Retrieve a review

GET/sites/{id}/reviews/{reviewId}

betastore:viewdefault (120/minute per token)

Get one review by id, including the store reply. Errors: FORBIDDEN, REVIEW_NOT_FOUND.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
reviewIdstring · pathrequired
Review id from reviews.list.

Response 200

idstringrequired
targetKind"PRODUCT" | "SERVICE"required
What the review is about: a product or a bookable service.
targetIdstringrequired
Id of the product or service.
targetTitlestring | nullrequired
Display name of the target when it still exists.
status"PENDING" | "APPROVED" | "REJECTED"required
source"BUYER" | "IMPORTED"required
BUYER reviews are tied to a paid order line or completed booking; IMPORTED ones were added by the store owner and are never shown as verified.
authorNamestringrequired
ratingintegerrequired
contentstring | nullrequired
replyobject | nullrequired
Store owner's public reply, if any.
reply.bodystringrequired
reply.repliedAtstringrequired
reply.repliedBystring | nullrequired
reviewDatestring | nullrequired
Original review date for imported reviews (ISO).
publishedAtstring | nullrequired
When the review became public (ISO); null while pending or rejected.
createdAtstringrequired

Errors

FORBIDDEN 403
REVIEW_NOT_FOUND 404

MCP tool reviews_get

curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/reviews/{reviewId}" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

Response

{
  "id": "rev_1",
  "targetKind": "PRODUCT",
  "targetId": "prod_example01",
  "targetTitle": "Strawberry Birthday Cake",
  "status": "PENDING",
  "source": "BUYER",
  "authorName": "Avery",
  "rating": 5,
  "content": "Arrived on time and tasted fresh.",
  "reply": null,
  "reviewDate": null,
  "publishedAt": null,
  "createdAt": "2026-10-06T08:00:00.000Z"
}

Delete imported

DELETE/sites/{id}/reviews/{reviewId}

betacommerce:managedefault (120/minute per token)

Delete a review that was imported by the store. Buyer reviews cannot be deleted; reject them instead. Errors: FORBIDDEN, REVIEW_NOT_FOUND, NOT_IMPORTED.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
reviewIdstring · pathrequired
Review id from reviews.list.

Response 200

idstringrequired
deletedtruerequired

Errors

FORBIDDEN 403
REVIEW_NOT_FOUND 404
NOT_IMPORTED 409

MCP tool reviews_delete_imported

curl -X DELETE "https://app.kanorio.com/api/v1/sites/{id}/reviews/{reviewId}" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

Response

{
  "id": "rev_2",
  "deleted": true
}

Approve a review

POST/sites/{id}/reviews/{reviewId}/approve

betacommerce:managedefault (120/minute per token)

Approve a review so it appears publicly and counts toward the rating. Idempotent when already approved. Errors: FORBIDDEN, REVIEW_NOT_FOUND.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
reviewIdstring · pathrequired
Review id from reviews.list.

Response 200

idstringrequired
targetKind"PRODUCT" | "SERVICE"required
What the review is about: a product or a bookable service.
targetIdstringrequired
Id of the product or service.
targetTitlestring | nullrequired
Display name of the target when it still exists.
status"PENDING" | "APPROVED" | "REJECTED"required
source"BUYER" | "IMPORTED"required
BUYER reviews are tied to a paid order line or completed booking; IMPORTED ones were added by the store owner and are never shown as verified.
authorNamestringrequired
ratingintegerrequired
contentstring | nullrequired
replyobject | nullrequired
Store owner's public reply, if any.
reply.bodystringrequired
reply.repliedAtstringrequired
reply.repliedBystring | nullrequired
reviewDatestring | nullrequired
Original review date for imported reviews (ISO).
publishedAtstring | nullrequired
When the review became public (ISO); null while pending or rejected.
createdAtstringrequired

Errors

FORBIDDEN 403
REVIEW_NOT_FOUND 404

MCP tool reviews_approve

curl -X POST "https://app.kanorio.com/api/v1/sites/{id}/reviews/{reviewId}/approve" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "id": "rev_1",
  "targetKind": "PRODUCT",
  "targetId": "prod_example01",
  "targetTitle": "Strawberry Birthday Cake",
  "status": "APPROVED",
  "source": "BUYER",
  "authorName": "Avery",
  "rating": 5,
  "content": "Arrived on time and tasted fresh.",
  "reply": null,
  "reviewDate": null,
  "publishedAt": "2026-10-28T09:00:00.000Z",
  "createdAt": "2026-10-06T08:00:00.000Z"
}

Reject a review

POST/sites/{id}/reviews/{reviewId}/reject

betacommerce:managedefault (120/minute per token)

Reject a review so it is not shown publicly. Use this for content that breaks your rules; do not reject reviews because of a low rating (consumer protection rules in the US, UK and EU forbid hiding negative reviews). Idempotent when already rejected. Errors: FORBIDDEN, REVIEW_NOT_FOUND.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
reviewIdstring · pathrequired
Review id from reviews.list.

Response 200

idstringrequired
targetKind"PRODUCT" | "SERVICE"required
What the review is about: a product or a bookable service.
targetIdstringrequired
Id of the product or service.
targetTitlestring | nullrequired
Display name of the target when it still exists.
status"PENDING" | "APPROVED" | "REJECTED"required
source"BUYER" | "IMPORTED"required
BUYER reviews are tied to a paid order line or completed booking; IMPORTED ones were added by the store owner and are never shown as verified.
authorNamestringrequired
ratingintegerrequired
contentstring | nullrequired
replyobject | nullrequired
Store owner's public reply, if any.
reply.bodystringrequired
reply.repliedAtstringrequired
reply.repliedBystring | nullrequired
reviewDatestring | nullrequired
Original review date for imported reviews (ISO).
publishedAtstring | nullrequired
When the review became public (ISO); null while pending or rejected.
createdAtstringrequired

Errors

FORBIDDEN 403
REVIEW_NOT_FOUND 404

MCP tool reviews_reject

curl -X POST "https://app.kanorio.com/api/v1/sites/{id}/reviews/{reviewId}/reject" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "id": "rev_1",
  "targetKind": "PRODUCT",
  "targetId": "prod_example01",
  "targetTitle": "Strawberry Birthday Cake",
  "status": "REJECTED",
  "source": "BUYER",
  "authorName": "Avery",
  "rating": 5,
  "content": "Arrived on time and tasted fresh.",
  "reply": null,
  "reviewDate": null,
  "publishedAt": null,
  "createdAt": "2026-10-06T08:00:00.000Z"
}

Reply to a review

PUT/sites/{id}/reviews/{reviewId}/reply

betacommerce:managedefault (120/minute per token)

Post or replace the store's public reply to a review (shown under the review). Pass body null to remove the reply. Errors: FORBIDDEN, REVIEW_NOT_FOUND, VALIDATION.

Parameters

idstring · pathrequired
Website id. Get it from sites.list or from sites.create.
reviewIdstring · pathrequired
Review id from reviews.list.

Request body

bodystring | nullrequired
Reply text, up to 2000 characters; null clears the reply.

Response 200

idstringrequired
targetKind"PRODUCT" | "SERVICE"required
What the review is about: a product or a bookable service.
targetIdstringrequired
Id of the product or service.
targetTitlestring | nullrequired
Display name of the target when it still exists.
status"PENDING" | "APPROVED" | "REJECTED"required
source"BUYER" | "IMPORTED"required
BUYER reviews are tied to a paid order line or completed booking; IMPORTED ones were added by the store owner and are never shown as verified.
authorNamestringrequired
ratingintegerrequired
contentstring | nullrequired
replyobject | nullrequired
Store owner's public reply, if any.
reply.bodystringrequired
reply.repliedAtstringrequired
reply.repliedBystring | nullrequired
reviewDatestring | nullrequired
Original review date for imported reviews (ISO).
publishedAtstring | nullrequired
When the review became public (ISO); null while pending or rejected.
createdAtstringrequired

Errors

FORBIDDEN 403
REVIEW_NOT_FOUND 404
VALIDATION 400

MCP tool reviews_reply

curl -X PUT "https://app.kanorio.com/api/v1/sites/{id}/reviews/{reviewId}/reply" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"Thank you! We bake every morning."}'

Response

{
  "id": "rev_1",
  "targetKind": "PRODUCT",
  "targetId": "prod_example01",
  "targetTitle": "Strawberry Birthday Cake",
  "status": "APPROVED",
  "source": "BUYER",
  "authorName": "Avery",
  "rating": 5,
  "content": "Arrived on time and tasted fresh.",
  "reply": {
    "body": "Thank you! We bake every morning.",
    "repliedAt": "2026-10-28T10:00:00.000Z",
    "repliedBy": null
  },
  "reviewDate": null,
  "publishedAt": "2026-10-28T09:00:00.000Z",
  "createdAt": "2026-10-06T08:00:00.000Z"
}