> ## Documentation Index
> Fetch the complete documentation index at: https://docs.virtual.fit/llms.txt
> Use this file to discover all available pages before exploring further.

# List storefront reviews

> Read full, paginated review evidence for a Custom JavaScript product.

Call this endpoint from the configured storefront origin when the shopper
wants the underlying reviews. Each item can include its stars, full text,
purchased options, customer photos or videos, reported measurements, and
extracted fit signals.

Results are limited to 50 reviews per page. Pass the returned `next_cursor`
unchanged to load the next page. Optional `variant_id` and `size` filters help
surface evidence that matches the shopper's current selection.


## OpenAPI

````yaml openapi.yaml GET /vfr/sites/{site_key}/reviews
openapi: 3.1.0
info:
  title: virtual.fit API
  version: 2.0.0
  description: Catalog sync, storefront fit evidence, and product recommendation endpoints.
servers:
  - url: https://api.virtual.fit
security:
  - bearerAuth: []
tags:
  - name: Catalog
  - name: Storefront evidence
  - name: Recommendations
paths:
  /vfr/sites/{site_key}/reviews:
    get:
      tags:
        - Storefront evidence
      summary: List product reviews
      description: |
        Browser-facing Custom JavaScript endpoint for shopper-controlled access
        to full review text, stars, media, purchased options, measurements, and
        fit signals. Results are cursor-paginated and the request must come from
        an allowed site origin.
      operationId: listStorefrontProductReviews
      parameters:
        - $ref: '#/components/parameters/SiteKey'
        - $ref: '#/components/parameters/StorefrontProductID'
        - $ref: '#/components/parameters/ReviewVariantID'
        - $ref: '#/components/parameters/ReviewSize'
        - $ref: '#/components/parameters/ReviewCursor'
        - $ref: '#/components/parameters/ReviewLimit'
      responses:
        '200':
          description: Paginated reviews for the product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogReviewListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/StorefrontForbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security: []
components:
  parameters:
    SiteKey:
      name: site_key
      in: path
      required: true
      description: Public Custom JavaScript site key.
      schema:
        type: string
        maxLength: 255
    StorefrontProductID:
      name: product_id
      in: query
      required: true
      description: Stable merchant product ID used during catalog sync.
      schema:
        type: string
        maxLength: 255
    ReviewVariantID:
      name: variant_id
      in: query
      required: false
      description: Optional stable merchant variant ID.
      schema:
        type: string
        maxLength: 255
    ReviewSize:
      name: size
      in: query
      required: false
      description: Optional exact source size label or size signature.
      schema:
        type: string
        maxLength: 255
    ReviewCursor:
      name: cursor
      in: query
      required: false
      description: Opaque `next_cursor` value from the previous response.
      schema:
        type: string
        maxLength: 2048
    ReviewLimit:
      name: limit
      in: query
      required: false
      description: Reviews per page.
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 20
  schemas:
    CatalogReviewListResponse:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          maxItems: 50
          items:
            $ref: '#/components/schemas/CatalogReview'
        next_cursor:
          type: string
          description: Opaque cursor for the next page. Omitted on the last page.
    CatalogReview:
      type: object
      properties:
        external_review_id:
          type: string
          maxLength: 255
          description: Preferred stable identity from the review source.
        external_id_scope:
          type: string
          maxLength: 255
        permalink:
          type: string
          format: uri
          maxLength: 8192
        title:
          type: string
          maxLength: 500
        body:
          type: string
          maxLength: 65536
        rating:
          type: number
          minimum: 0
          maximum: 5
        language:
          type: string
          maxLength: 255
        locale:
          type: string
          maxLength: 255
        author_display_name:
          type: string
          maxLength: 255
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        verified_purchase:
          type: boolean
        incentivized:
          type: boolean
        badges:
          type: array
          items:
            type: string
        helpful_count:
          type: integer
          minimum: 0
        merchant_response:
          type: object
          additionalProperties: true
        purchased_variant:
          $ref: '#/components/schemas/CatalogReviewVariant'
        media:
          type: array
          maxItems: 12
          items:
            $ref: '#/components/schemas/CatalogReviewMedia'
        measurements:
          type: array
          maxItems: 6
          items:
            $ref: '#/components/schemas/CatalogReviewMeasurementSet'
        fit_signals:
          type: array
          maxItems: 24
          items:
            $ref: '#/components/schemas/CatalogReviewFitSignal'
        deleted:
          type: boolean
          default: false
          description: >-
            Deletes the review association. Requires a stable review ID or
            permalink.
      anyOf:
        - required:
            - external_review_id
        - required:
            - permalink
        - required:
            - title
        - required:
            - body
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    CatalogReviewVariant:
      type: object
      properties:
        source_variant_id:
          type: string
          maxLength: 255
        sku:
          type: string
          maxLength: 255
        label:
          type: string
          maxLength: 255
        option_values:
          type: object
          maxProperties: 20
          additionalProperties:
            type: string
        size_signature:
          type: string
          maxLength: 255
      description: >-
        Send any identifiers available for the purchased variant. Unresolved
        source values are preserved.
    CatalogReviewMedia:
      type: object
      required:
        - url
      properties:
        external_media_id:
          type: string
          maxLength: 255
        url:
          type: string
          format: uri
          maxLength: 8192
        kind:
          type: string
          enum:
            - image
            - video
          default: image
        caption:
          type: string
        alt_text:
          type: string
        width:
          type: integer
          minimum: 0
        height:
          type: integer
          minimum: 0
        position:
          type: integer
          minimum: 0
    CatalogReviewMeasurementSet:
      type: object
      properties:
        subject_kind:
          type: string
          enum:
            - reviewer
          default: reviewer
        basis:
          type: string
          enum:
            - body
            - unknown
          default: unknown
        source_key:
          type: string
        source_kind:
          type: string
          default: public_review
        capture_method:
          type: string
        size_label:
          type: string
        option_selector:
          type: object
          additionalProperties:
            type: string
        confidence:
          type: number
          minimum: 0
          maximum: 1
        values:
          type: array
          maxItems: 32
          items:
            $ref: '#/components/schemas/CatalogMeasurementValue'
    CatalogReviewFitSignal:
      type: object
      required:
        - dimension_code
        - score
        - confidence
        - evidence
      properties:
        dimension_code:
          type: string
          enum:
            - overall
            - bust
            - chest
            - underbust
            - waist
            - hips
            - shoulder_width
            - sleeve_length
            - total_length
            - inseam
            - front_rise
            - back_rise
            - thigh
            - leg_opening
            - foot_width
        score:
          type: integer
          minimum: -2
          maximum: 2
          description: >-
            Negative means tighter, smaller, or shorter. Positive means looser,
            larger, or longer.
        confidence:
          type: number
          minimum: 0
          maximum: 1
        evidence:
          type: string
          maxLength: 4096
        source_kind:
          type: string
          enum:
            - structured
            - deterministic
            - llm
            - vlm
            - manual
          default: structured
    CatalogMeasurementValue:
      type: object
      required:
        - dimension_code
        - unit
      properties:
        dimension_code:
          type: string
          enum:
            - height
            - weight
            - bust
            - chest
            - underbust
            - waist
            - hips
            - shoulder_width
            - arm_length
            - sleeve_length
            - total_length
            - inseam
            - front_rise
            - back_rise
            - thigh
            - leg_opening
            - foot_length
            - foot_width
        value:
          type: number
          minimum: 0
        min_value:
          type: number
          minimum: 0
        max_value:
          type: number
          minimum: 0
        unit:
          type: string
          enum:
            - cm
            - kg
          description: Use kg for weight and cm for every length.
        raw_label:
          type: string
        raw_value:
          type: string
        raw_unit:
          type: string
        confidence:
          type: number
          minimum: 0
          maximum: 1
      anyOf:
        - required:
            - value
        - required:
            - min_value
        - required:
            - max_value
  responses:
    BadRequest:
      description: Invalid field or inconsistent catalog data.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    StorefrontForbidden:
      description: The request origin is not allowed for this site key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Site, product, variant, or recommendation context not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Keep the virtual.fit API key on your server.

````