Reviews

The ReviewsService class (accessed via client.reviews) handles the storefront side of product reviews — listing approved reviews, submitting a review, deleting your own review, and surfacing helpfulness votes.

Overview

Reviews follow a moderation lifecycle:

A logged-in customer submits a review. It starts as pending.
The store approves or rejects it. Approval happens in the store’s admin.
Once approved, the review appears in public listing results.

Key type behavior:

Publishable keys — list and get approved reviews, submit a review (with a customer credential), delete the customer’s own review (with a customer credential), mark reviews helpful. A customer credential is either xAuthToken (session JWT) or xExternalAuth (bring-your-own-auth assertion).
Secret keys — the same storefront actions, for server-side use.

`listReviews`

Returns reviews for a product. Includes an aggregate summary block (average rating and star distribution) regardless of the status filter applied.

const { reviews, pagination, summary } = await client.reviews.listReviews({
  productId: '0186665f-f0a1-4c79-976a-919b5b1c2daa',
  status: 'approved',
  sort: 'newest',
  limit: 20,
});

console.log(`${summary.total_reviews} reviews, avg ${summary.average_rating}★`);

Parameters

Name	Type	Required	Description
`productId`	`string`	Yes	UUID of the product to list reviews for.
`variantId`	`string`	No	Filter to reviews mentioning a specific variant.
`status`	`'approved' \| 'pending' \| 'rejected' \| 'all'`	No	Default: `'approved'`. Publishable keys always see only approved reviews regardless of this value.
`rating`	`number`	No	Filter to reviews with this exact star rating (1–5).
`sort`	`'newest' \| 'oldest' \| 'highest' \| 'lowest'`	No	Default: `'newest'`.
`limit`	`number`	No	Page size, 1–100. Default: 20.
`cursor`	`string`	No	Pagination cursor from the previous response’s `pagination.next_cursor`.

Response shape

{
  reviews: Review[];
  pagination: {
    limit: number;
    has_more: boolean;
    next_cursor: string | null;
  };
  summary: {
    total_reviews: number;
    average_rating: number;
    five_star: number;
    four_star: number;
    three_star: number;
    two_star: number;
    one_star: number;
    verified_count: number;
  };
}

Response (200)

{
  "reviews": [
    {
      "id": "11bc03d9-d1cb-4833-b9d2-f0b016104cde",
      "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "variant_id": null,
      "order_id": null,
      "customer_id": "73ec7ad0-d9aa-4ee2-a382-efa690eaab01",
      "customer_name": "Jane Doe",
      "rating": 5,
      "title": "Outstanding quality",
      "body": "Exactly as described — fast shipping and great build quality. Would buy again.",
      "media_urls": [],
      "status": "approved",
      "rejection_reason": null,
      "helpful_count": 0,
      "verified_purchase": false,
      "created_at": "2026-06-20T10:44:28.706637+00:00",
      "updated_at": "2026-06-20T10:44:28.706637+00:00"
    }
  ],
  "pagination": { "limit": 20, "has_more": false, "next_cursor": null },
  "summary": {
    "total_reviews": 1,
    "average_rating": 5,
    "five_star": 1,
    "four_star": 0,
    "three_star": 0,
    "two_star": 0,
    "one_star": 0,
    "verified_count": 0
  }
}

`getReview`

Returns a single review by ID. Publishable keys receive 404 for pending or rejected reviews — only approved reviews are visible.

const { review } = await client.reviews.getReview({
  id: '11bc03d9-d1cb-4833-b9d2-f0b016104cde',
});

Response 200:

{
  "review": {
    "id": "11bc03d9-d1cb-4833-b9d2-f0b016104cde",
    "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
    "variant_id": null,
    "order_id": null,
    "customer_id": "73ec7ad0-d9aa-4ee2-a382-efa690eaab01",
    "customer_name": "Jane Doe",
    "rating": 5,
    "title": "Outstanding quality",
    "body": "Exactly as described — fast shipping and great build quality. Would buy again.",
    "media_urls": [],
    "status": "approved",
    "rejection_reason": null,
    "helpful_count": 1,
    "verified_purchase": false,
    "created_at": "2026-06-20T10:44:28.706637+00:00",
    "updated_at": "2026-06-20T10:44:28.706637+00:00"
  }
}

The Review object is scoped to a single product and customer; it carries no store_id field. The reviewer’s customer_name is captured from their profile at submission time, so you never supply it.

`submitReview`

Submits a review on behalf of a logged-in customer. Requires both your API key and a customer credential (xAuthToken session JWT or xExternalAuth assertion).

Pass the customer’s session token (obtained from POST /v1/auth/login) in the xAuthToken parameter. Reviews start as pending and must be approved before they appear publicly.

const { review } = await client.reviews.submitReview({
  xAuthToken: customerSessionToken,
  requestBody: {
    product_id: 'd8cea277-9bb6-4942-b9e9-2f2ac351509f',
    rating: 5,
    title: 'Absolutely love it',
    body: "Best purchase I've made this year. Quality is outstanding.",
    order_id: yourOrderId, // optional — a matching order unlocks verified_purchase
  },
});
// review.status === 'pending' — awaiting merchant approval

Response 201 — the review is created pending and customer_name is filled in from the account:

{
  "review": {
    "id": "11bc03d9-d1cb-4833-b9d2-f0b016104cde",
    "product_id": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
    "variant_id": null,
    "order_id": null,
    "customer_id": "73ec7ad0-d9aa-4ee2-a382-efa690eaab01",
    "customer_name": "Jane Doe",
    "rating": 5,
    "title": "Absolutely love it",
    "body": "Best purchase I've made this year. Quality is outstanding.",
    "media_urls": [],
    "status": "pending",
    "rejection_reason": null,
    "helpful_count": 0,
    "verified_purchase": false,
    "created_at": "2026-06-20T10:44:28.706637+00:00",
    "updated_at": "2026-06-20T10:44:28.706637+00:00"
  }
}

Parameters

Name	Type	Required	Description
`xAuthToken`	`string`	Yes	Customer session JWT from `POST /v1/auth/login` or `POST /v1/auth/verify-otp`.
`requestBody.product_id`	`string`	Yes	UUID of the product being reviewed.
`requestBody.rating`	`number`	Yes	Star rating 1–5.
`requestBody.variant_id`	`string`	No	Specific variant being reviewed.
`requestBody.order_id`	`string`	No	Optional order UUID. If provided and the order belongs to this customer, the review is marked `verified_purchase: true`. If omitted or the order doesn’t match, the review is still accepted with `verified_purchase: false`.
`requestBody.title`	`string`	No	Short headline for the review.
`requestBody.body`	`string`	No	Full review text.
`requestBody.media_urls`	`string[]`	No	Image or video URLs attached to the review.

order_id is optional — reviews are not gated on purchase history. Customers can review products they received as gifts, bought in-store, or purchased before creating an account. Providing a matching order_id simply unlocks the verified_purchase: true badge on the review. If the order doesn’t belong to the authenticated customer, the review is accepted without the badge — no error is returned. customer_name on the returned review object is automatically populated from the customer’s profile at submission time. You don’t supply it — it’s read from the account. Duplicate prevention: A customer may only have one non-rejected review per product. A second submission returns 409 Conflict.

`deleteReview`

Permanently deletes a review submitted by the authenticated customer. A customer can only delete the review they wrote. Requires the review author’s customer session token in xAuthToken.

// Customer deletes their own review
await client.reviews.deleteReview({
  id: '11bc03d9-d1cb-4833-b9d2-f0b016104cde',
  xAuthToken: customerSessionToken,
});
// returns { success: true, message: 'Review deleted' }

Parameters

Name	Type	Required	Description
`id`	`string`	Yes	UUID of the review to delete.
`xAuthToken`	`string`	Yes	Customer session JWT for the review’s author, from `POST /v1/auth/login` or `POST /v1/auth/verify-otp`.

`markReviewHelpful`

Increments the helpful_count on an approved review. Use this to surface the most useful reviews in your storefront UI.

const { helpful_count } = await client.reviews.markReviewHelpful({
  id: '11bc03d9-d1cb-4833-b9d2-f0b016104cde',
});
// returns { helpful_count: 1 }
console.log(`${helpful_count} people found this helpful`);

Only approved reviews accept votes — calling this on a pending or rejected review returns 404. No server-side deduplication is applied per customer. If you need per-customer dedup, track votes client-side (e.g. in localStorage) before calling this method.

Displaying reviews on a storefront

async function loadProductReviews(productId: string) {
  const { reviews, pagination, summary } = await client.reviews.listReviews({
    productId,
    sort: 'newest',
    limit: 10,
  });

  // Render star distribution
  renderRatingSummary(summary);

  // Render individual reviews
  for (const review of reviews) {
    renderReview(review);
  }

  // Load more button
  if (pagination.has_more) {
    return pagination.next_cursor;
  }
}

Response codes

Code	Meaning
`200`	Success
`201`	Review submitted (pending moderation)
`400`	Invalid request — missing required field or bad UUID
`401`	Missing or invalid API key
`403`	Attempting to delete a review that the authenticated customer did not write
`404`	Review not found, or review is not approved (publishable key)
`409`	Duplicate review — customer already has a non-rejected review for this product
`429`	Rate limit exceeded
`500`	Unexpected error

Get Started

Core Commerce

Discovery

Checkout & Logistics

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

Overview

`listReviews`

`getReview`

`submitReview`

`deleteReview`

`markReviewHelpful`

Displaying reviews on a storefront

Response codes

​Overview

​listReviews

​getReview

​submitReview

​deleteReview

​markReviewHelpful

​Displaying reviews on a storefront

​Response codes

Overview

`listReviews`

`getReview`

`submitReview`

`deleteReview`

`markReviewHelpful`

Displaying reviews on a storefront

Response codes