Product reviews

Product reviews are customer-submitted ratings + comments on products, rendered on the storefront. Use these endpoints to fetch reviews per product, submit a review (customer-authenticated), and manage your own review (update/delete by the author).

The /v1 operations here are the API-key surface for reading and moderating reviews, plus the review photo upload, which a storefront calls with the sales-channel id and a signed-in customer token.

The calls a storefront makes for a shopper (list a product’s reviews, read, submit, update and delete their own review) are on Storefront reviews.

Upload a review photo

Uploads one photo to attach to a review. The customer must be allowed to review the product, and photos must be enabled for the store. JPEG, PNG, WebP or GIF, up to 5 MB, at most the per-review photo limit. Returns a storage key to send in submitProductReview and a URL for a preview.

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

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.

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

filestring

The photo to attach. JPEG, PNG, WebP or GIF; 5 MB maximum, one file per request.

curl -X POST "https://api.brainerce.com/api/vc/string/products/string/review-photo" \
  -H "origin: string" \
  -H "authorization: string" \
  -H "X-SDK-Version: string" \
  -F file="string"

curl -X POST "https://api.brainerce.com/api/vc/string/products/string/review-photo" \  -H "origin: string" \  -H "authorization: string" \  -H "X-SDK-Version: string" \  -F file="string"

{
  "url": "https://cdn.brainerce.com/customizations/abc123.png",
  "key": "customizations/abc123.png",
  "width": 1200,
  "height": 800
}

{
  "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}/review-photo"
}

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

{
  "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}/review-photo"
}

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

{
  "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}/review-photo"
}

List reviews for a product (admin view, includes hidden)

Lists the reviews of a product for moderation, hidden ones included by default, newest first. An unknown product returns an empty page.

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → API keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Path Parameters

productIdstring

Product ID

Query Parameters

page?integer

1-based page number.

Default1

Range1 <= value

limit?integer

Items per page. Default 20. Maximum 100.

Default20

Range1 <= value <= 100

visibility?string

Which reviews to list.

Default"all"

Value in"visible" | "hidden" | "all"

curl -X GET "https://api.brainerce.com/api/v1/products/string/reviews?page=1&limit=20&visibility=visible"

curl -X GET "https://api.brainerce.com/api/v1/products/string/reviews?page=1&limit=20&visibility=visible"

{
  "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",
      "customerId": "clx1a2b3c4d5e6f7g8h9",
      "authorEmail": "[email protected]",
      "orderId": "clx1a2b3c4d5e6f7g8h9",
      "updatedAt": "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,
          "assetKey": "reviews/photo-1.jpg",
          "approvedAt": "2019-08-24T14:15:22Z",
          "hiddenAt": "2019-08-24T14:15:22Z",
          "createdAt": "2019-08-24T14:15:22Z"
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 137,
    "totalPages": 7
  }
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/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/v1/products/{productId}/reviews"
}

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

Submit a product review (server-to-server)

Supports Idempotency-Key header for safe retries.

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

productIdstring

Product ID

Header Parameters

Idempotency-Key?string

Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.

Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255

Request Body

authorNamestring

Reviewer display name. 1-100 chars, no HTML angle brackets (a basic XSS guard; full sanitization happens server-side).

Match^[^<>]+$

Length1 <= length <= 100

authorEmail?string

Optional reviewer email, used for verified-buyer matching. It is never mailed: Brainerce sends no notification when a review is submitted or published, and there is no template for one.

Formatemail

Lengthlength <= 200

ratinginteger

Star rating, 1-5 (integer).

Range1 <= value <= 5

body?string

Review body (≤ 5000 chars). Markdown is rendered as plain text, and links are stripped.

Lengthlength <= 5000

imageKeys?array<string>

Media library storage keys to attach as review photos, in display order. This is the import path: upload the images through the normal media endpoints first, then pass their keys here. Keys must belong to the same store. Photos imported this way publish immediately regardless of the store's approval setting, since a server-to-server caller has already vetted them.

Itemsitems <= 5

curl -X POST "https://api.brainerce.com/api/v1/products/string/reviews" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "authorName": "Jane D.",
    "rating": 5
  }'

curl -X POST "https://api.brainerce.com/api/v1/products/string/reviews" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "authorName": "Jane 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/v1/products/{productId}/reviews"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/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/v1/products/{productId}/reviews"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/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/v1/products/{productId}/reviews"
}

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

Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255

curl -X PATCH "https://api.brainerce.com/api/v1/reviews/string/hide" \
  -H "Idempotency-Key: string"

curl -X PATCH "https://api.brainerce.com/api/v1/reviews/string/hide" \  -H "Idempotency-Key: string"

{
  "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",
  "customerId": "clx1a2b3c4d5e6f7g8h9",
  "authorEmail": "[email protected]",
  "orderId": "clx1a2b3c4d5e6f7g8h9",
  "updatedAt": "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,
      "assetKey": "reviews/photo-1.jpg",
      "approvedAt": "2019-08-24T14:15:22Z",
      "hiddenAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ]
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/reviews/{id}/hide"
}

{
  "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/v1/reviews/{id}/hide"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/reviews/{id}/hide"
}

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

Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255

curl -X PATCH "https://api.brainerce.com/api/v1/reviews/string/show" \
  -H "Idempotency-Key: string"

curl -X PATCH "https://api.brainerce.com/api/v1/reviews/string/show" \  -H "Idempotency-Key: string"

{
  "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",
  "customerId": "clx1a2b3c4d5e6f7g8h9",
  "authorEmail": "[email protected]",
  "orderId": "clx1a2b3c4d5e6f7g8h9",
  "updatedAt": "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,
      "assetKey": "reviews/photo-1.jpg",
      "approvedAt": "2019-08-24T14:15:22Z",
      "hiddenAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ]
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/reviews/{id}/show"
}

{
  "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/v1/reviews/{id}/show"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/reviews/{id}/show"
}

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

Upload a review photo

Authorization

Path Parameters

Header Parameters

Request Body

List reviews for a product (admin view, includes hidden)

Authorization

Path Parameters

Query Parameters

Submit a product review (server-to-server)

Authorization

Path Parameters

Header Parameters

Request Body

Hide a review from the storefront

Authorization

Path Parameters

Header Parameters

Unhide a previously hidden review

Authorization

Path Parameters

Header Parameters

Product reviews

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