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).

Upload a 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

productIdstring

Header Parameters

originstring

authorizationstring

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

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

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

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

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → Authentication → 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?number

limit?number

visibility?string

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

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

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

{
  "data": [
    {
      "id": "string",
      "productId": "string",
      "authorName": "string",
      "rating": 1,
      "body": "string",
      "verifiedPurchase": true,
      "hiddenAt": "2019-08-24T14:15:22Z",
      "createdAt": "2019-08-24T14:15:22Z",
      "customerId": "string",
      "authorEmail": "[email protected]",
      "orderId": "string",
      "updatedAt": "2019-08-24T14:15:22Z",
      "images": [
        {
          "id": "string",
          "url": "string",
          "thumbnailUrl": "string",
          "width": 0,
          "height": 0,
          "position": 0,
          "assetKey": "string",
          "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": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products/{productId}/reviews"
}

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).

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.

Lengthlength <= 200

ratingnumber

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": "string",
  "productId": "string",
  "authorName": "string",
  "rating": 1,
  "body": "string",
  "verifiedPurchase": true,
  "hiddenAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "images": [
    {
      "id": "string",
      "url": "string",
      "thumbnailUrl": "string",
      "width": 0,
      "height": 0,
      "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"
}

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": "string",
  "productId": "string",
  "authorName": "string",
  "rating": 1,
  "body": "string",
  "verifiedPurchase": true,
  "hiddenAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "customerId": "string",
  "authorEmail": "[email protected]",
  "orderId": "string",
  "updatedAt": "2019-08-24T14:15:22Z",
  "images": [
    {
      "id": "string",
      "url": "string",
      "thumbnailUrl": "string",
      "width": 0,
      "height": 0,
      "position": 0,
      "assetKey": "string",
      "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"
}

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": "string",
  "productId": "string",
  "authorName": "string",
  "rating": 1,
  "body": "string",
  "verifiedPurchase": true,
  "hiddenAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "customerId": "string",
  "authorEmail": "[email protected]",
  "orderId": "string",
  "updatedAt": "2019-08-24T14:15:22Z",
  "images": [
    {
      "id": "string",
      "url": "string",
      "thumbnailUrl": "string",
      "width": 0,
      "height": 0,
      "position": 0,
      "assetKey": "string",
      "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"
}

Upload a review photo

Authorization

Path Parameters

Header Parameters

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

On this page

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

On this page