Skip to content

List a product's reviews

GET
/public/stores/{storeRef}/products/{productId}/reviews
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/public/stores/example/products/1/reviews?limit=20&offset=0&sort_by=created_at&sort_order=asc&include_replies=false' \
--header 'x-storefront-api-key: <x-storefront-api-key>'

Returns a page of the product’s approved reviews. Reviewer emails, account and order details and moderation data are never included. Page with limit and offset, sort with sort_by and sort_order, filter by rating or has_media, and set include_replies to add the store’s visible replies. A non-numeric productId currently answers 500 instead of 400.

productId
required
integer

The product ID.

storeRef
required
string

The store’s ref, as returned by GET /stores.

limit
number
>= 1 <= 10000

Example

20

Number of items per page

offset
number

Example

0

Number of items to skip

sort_by
string
Allowed values: created_at updated_at rating display_order is_featured

Sort field

sort_order
string
Allowed values: asc desc
include_replies
boolean

Example

true

Include each review’s replies in the response

rating
number
>= 1 <= 5

Filter to reviews with an exact star rating

has_media
boolean

Filter to reviews that include media

Media typeapplication/json
object
data
required
Array<object>
object
variant_id

ID of the reviewed variant, or null.

number
nullable
variant_name

Name of the reviewed variant, or null.

string
nullable
reviewer_avatar

URL of the reviewer’s avatar, or null.

string
nullable
title

Review title, or null.

string
nullable
media
required

Photos or other media attached to the review: a list of objects such as { "url": "https://...", "type": "image" }.

Array<object>
object
key
additional properties
any
display_order

Position used when sorting by display_order, or null.

number
nullable
review_date

The date shown for the review, as an ISO 8601 timestamp, or null.

string
nullable
review_replies

The store’s visible replies. Present only when include_replies is true.

Array<object>
object
id
required

Reply ID.

string
review_id
required

ID of the review the reply answers.

string
content
required

Reply text.

string
is_visible
required

Always true: hidden replies are not returned.

boolean
created_at
required

When the reply was created, as an ISO 8601 timestamp.

string
updated_at
required

When the reply was last updated, as an ISO 8601 timestamp.

string
id
required

Review ID.

string
product_id
required

ID of the reviewed product.

number
product_name
required

Name of the reviewed product when the review was written.

string
reviewer_name
required

Reviewer’s name.

string
is_verified_buyer
required

Whether the reviewer bought the product from the store.

boolean
rating
required

Star rating, 1 to 5.

number
content
required

Review text.

string
pros
required

What the reviewer liked.

Array<string>
cons
required

What the reviewer disliked.

Array<string>
status
required

Always APPROVED: only approved reviews are returned.

string
is_featured
required

Whether the store features the review.

boolean
is_pinned
required

Whether the review is pinned to the top of the list.

boolean
created_at
required

When the review was created, as an ISO 8601 timestamp.

string
updated_at
required

When the review was last updated, as an ISO 8601 timestamp.

string
meta
required
object
total
required

Total number of items matching the request.

number
limit
required

Maximum number of items in this page.

number
offset
required

Number of items skipped before this page.

number
page
required

Current page number, starting at 1.

number
totalPages
required

Total number of pages.

number
hasNext
required

Whether a next page exists.

boolean
hasPrev
required

Whether a previous page exists.

boolean

Example generated

{
"data": [
{
"variant_id": 1,
"variant_name": "example",
"reviewer_avatar": "example",
"title": "example",
"media": [
{}
],
"display_order": 1,
"review_date": "example",
"review_replies": [
{
"id": "example",
"review_id": "example",
"content": "example",
"is_visible": true,
"created_at": "example",
"updated_at": "example"
}
],
"id": "example",
"product_id": 1,
"product_name": "example",
"reviewer_name": "example",
"is_verified_buyer": true,
"rating": 1,
"content": "example",
"pros": [
"example"
],
"cons": [
"example"
],
"status": "example",
"is_featured": true,
"is_pinned": true,
"created_at": "example",
"updated_at": "example"
}
],
"meta": {
"total": 1,
"limit": 1,
"offset": 1,
"page": 1,
"totalPages": 1,
"hasNext": true,
"hasPrev": true
}
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}