Storefront reviews

Product reviews on a storefront. Listing a product’s visible reviews needs only the sales-channel id (vc_*). Reading, submitting, updating and deleting the signed-in shopper’s own review also need that customer’s Authorization: Bearer token, and a shopper can only touch their own review. Photo uploads for a review are on the Product reviews and Products pages.

List product reviews

Lists the visible reviews of a product. The default order photos_first puts reviews with photos above the rest, newest first within each group.

Authorization

X-Sales-Channel-Origin<token>

For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.

In: header

Path Parameters

connectionIdstring

Sales channel ID (vc_*), the canonical salesChannelId. connectionId is the deprecated name of the same value and is still the literal path segment.

productIdstring

Product id.

Query Parameters

sort?string

photos_first puts reviews with photos above the rest, newest first within each group. newest is plain newest first.

Default"photos_first"

Value in"photos_first" | "newest"

page?number

Page number, starting at 1.

Default1

Range1 <= value

limit?number

Page size, 1 to 50.

Default20

Range1 <= value <= 50

Header Parameters

originstring

Origin of the storefront page making the call, for example https://shop.example.com. Required: a request with no Origin header is refused with 403. On a LIVE channel its host must equal the channel's registered domain (or one of its subdomains) or match an allowed origin. A TEST channel with no domain accepts any origin; once a domain is set it is matched as on LIVE.

X-SDK-Version?string

Version of the calling SDK (the Brainerce SDK sends it automatically). Informational: it is recorded on the channel and never changes the response.

curl -X GET "https://api.brainerce.com/api/vc/string/products/string/reviews?sort=photos_first&page=1&limit=20" \
  -H "origin: string" \
  -H "X-SDK-Version: string"

curl -X GET "https://api.brainerce.com/api/vc/string/products/string/reviews?sort=photos_first&page=1&limit=20" \  -H "origin: string" \  -H "X-SDK-Version: string"

{
  "data": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "productId": "clx1a2b3c4d5e6f7g8h9",
      "authorName": "Dana C.",
      "rating": 5,
      "body": "Fits perfectly.",
      "verifiedPurchase": true,
      "hiddenAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z",
      "images": [
        {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "url": "https://cdn.example.com/reviews/photo-1.jpg",
          "thumbnailUrl": "https://cdn.example.com/reviews/photo-1-thumb.jpg",
          "width": 1200,
          "height": 800,
          "position": 0
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 137,
    "totalPages": 7
  }
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews"
}

Submit product review

Posts a review for a product. Only customers who purchased the product can review, and only once; edit an existing review with PATCH. Photos are attached by the storage keys returned by products/{productId}/review-photo.

Authorization

X-Sales-Channel-Origin<token>

For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.

In: header

Path Parameters

connectionIdstring

Sales channel ID (vc_*), the canonical salesChannelId. connectionId is the deprecated name of the same value and is still the literal path segment.

productIdstring

Product id.

Header Parameters

originstring

authorizationstring

Customer token as Bearer <token>, returned by customers/login, customers/register or the OAuth callback. Expires after 7 days. It is a customer token, never an API key.

X-SDK-Version?string

Version of the calling SDK (the Brainerce SDK sends it automatically). Informational: it is recorded on the channel and never changes the response.

Request Body

ratingnumber

Star rating, 1 to 5.

Range1 <= value <= 5

body?string

Review text, plain text.

Lengthlength <= 5000

imageKeys?array<string>

Storage keys returned by products/{productId}/review-photo, in display order. On update the set is replaced: keys left out are detached. At most 5 photos, each key up to 512 characters.

Itemsitems <= 5

curl -X POST "https://api.brainerce.com/api/vc/string/products/string/reviews" \
  -H "origin: string" \
  -H "authorization: string" \
  -H "X-SDK-Version: string" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5
  }'

curl -X POST "https://api.brainerce.com/api/vc/string/products/string/reviews" \  -H "origin: string" \  -H "authorization: string" \  -H "X-SDK-Version: string" \  -H "Content-Type: application/json" \  -d '{    "rating": 5  }'

{
  "id": "clx1a2b3c4d5e6f7g8h9",
  "productId": "clx1a2b3c4d5e6f7g8h9",
  "authorName": "Dana C.",
  "rating": 5,
  "body": "Fits perfectly.",
  "verifiedPurchase": true,
  "hiddenAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "images": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "url": "https://cdn.example.com/reviews/photo-1.jpg",
      "thumbnailUrl": "https://cdn.example.com/reviews/photo-1-thumb.jpg",
      "width": 1200,
      "height": 800,
      "position": 0
    }
  ]
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews"
}

{
  "statusCode": 409,
  "code": "CONFLICT",
  "message": "The request conflicts with the current state of the resource",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews"
}

Get my product review

Returns the signed-in customer review state for a product: whether they may review it (purchased it) and their existing review, if any.

Authorization

X-Sales-Channel-Origin<token>

For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.

In: header

Path Parameters

connectionIdstring

Sales channel ID (vc_*), the canonical salesChannelId. connectionId is the deprecated name of the same value and is still the literal path segment.

productIdstring

Product id.

Header Parameters

originstring

authorizationstring

Customer token as Bearer <token>, returned by customers/login, customers/register or the OAuth callback. Expires after 7 days. It is a customer token, never an API key.

X-SDK-Version?string

Version of the calling SDK (the Brainerce SDK sends it automatically). Informational: it is recorded on the channel and never changes the response.

curl -X GET "https://api.brainerce.com/api/vc/string/products/string/reviews/me" \
  -H "origin: string" \
  -H "authorization: string" \
  -H "X-SDK-Version: string"

curl -X GET "https://api.brainerce.com/api/vc/string/products/string/reviews/me" \  -H "origin: string" \  -H "authorization: string" \  -H "X-SDK-Version: string"

{
  "eligible": true,
  "reason": "no_eligible_order",
  "myReview": {
    "id": "clx1a2b3c4d5e6f7g8h9",
    "productId": "clx1a2b3c4d5e6f7g8h9",
    "authorName": "Dana C.",
    "rating": 5,
    "body": "Fits perfectly.",
    "verifiedPurchase": true,
    "hiddenAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "images": [
      {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "url": "https://cdn.example.com/reviews/photo-1.jpg",
        "thumbnailUrl": "https://cdn.example.com/reviews/photo-1-thumb.jpg",
        "width": 1200,
        "height": 800,
        "position": 0
      }
    ]
  },
  "photos": {
    "enabled": true,
    "maxPerReview": 5,
    "maxBytes": 5242880,
    "requiresApproval": true
  },
  "myImages": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "url": "https://cdn.example.com/reviews/photo-1.jpg",
      "thumbnailUrl": "https://cdn.example.com/reviews/photo-1-thumb.jpg",
      "width": 1200,
      "height": 800,
      "position": 0,
      "assetKey": "reviews/photo-1.jpg",
      "approvedAt": "2019-08-24T14:15:22Z",
      "hiddenAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ]
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

Update my product review

Edits the signed-in customer own review of a product.

Authorization

X-Sales-Channel-Origin<token>

For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.

In: header

Path Parameters

connectionIdstring

Sales channel ID (vc_*), the canonical salesChannelId. connectionId is the deprecated name of the same value and is still the literal path segment.

productIdstring

Product id.

Header Parameters

originstring

authorizationstring

Customer token as Bearer <token>, returned by customers/login, customers/register or the OAuth callback. Expires after 7 days. It is a customer token, never an API key.

X-SDK-Version?string

Version of the calling SDK (the Brainerce SDK sends it automatically). Informational: it is recorded on the channel and never changes the response.

Request Body

ratingnumber

Star rating, 1 to 5.

Range1 <= value <= 5

body?string

Review text, plain text.

Lengthlength <= 5000

imageKeys?array<string>

Storage keys returned by products/{productId}/review-photo, in display order. On update the set is replaced: keys left out are detached. At most 5 photos, each key up to 512 characters.

Itemsitems <= 5

curl -X PATCH "https://api.brainerce.com/api/vc/string/products/string/reviews/me" \
  -H "origin: string" \
  -H "authorization: string" \
  -H "X-SDK-Version: string" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5
  }'

curl -X PATCH "https://api.brainerce.com/api/vc/string/products/string/reviews/me" \  -H "origin: string" \  -H "authorization: string" \  -H "X-SDK-Version: string" \  -H "Content-Type: application/json" \  -d '{    "rating": 5  }'

{
  "id": "clx1a2b3c4d5e6f7g8h9",
  "productId": "clx1a2b3c4d5e6f7g8h9",
  "authorName": "Dana C.",
  "rating": 5,
  "body": "Fits perfectly.",
  "verifiedPurchase": true,
  "hiddenAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "images": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "url": "https://cdn.example.com/reviews/photo-1.jpg",
      "thumbnailUrl": "https://cdn.example.com/reviews/photo-1-thumb.jpg",
      "width": 1200,
      "height": 800,
      "position": 0
    }
  ]
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

Delete my product review

Deletes the signed-in customer own review of a product.

Authorization

X-Sales-Channel-Origin<token>

For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.

In: header

Path Parameters

connectionIdstring

Sales channel ID (vc_*), the canonical salesChannelId. connectionId is the deprecated name of the same value and is still the literal path segment.

productIdstring

Product id.

Header Parameters

originstring

authorizationstring

Customer token as Bearer <token>, returned by customers/login, customers/register or the OAuth callback. Expires after 7 days. It is a customer token, never an API key.

X-SDK-Version?string

Version of the calling SDK (the Brainerce SDK sends it automatically). Informational: it is recorded on the channel and never changes the response.

curl -X DELETE "https://api.brainerce.com/api/vc/string/products/string/reviews/me" \
  -H "origin: string" \
  -H "authorization: string" \
  -H "X-SDK-Version: string"

curl -X DELETE "https://api.brainerce.com/api/vc/string/products/string/reviews/me" \  -H "origin: string" \  -H "authorization: string" \  -H "X-SDK-Version: string"

Empty

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/products/{productId}/reviews/me"
}

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default

Example default