openapi: 3.0.1
info:
  title: Judge.me Products Reviews API
  description: REST API for the Judge.me product reviews platform for Shopify and other e-commerce storefronts. Endpoints let you list and create reviews, resolve products, send review request emails, and fetch ready-to-render review widget HTML. Requests are authenticated with a shop_domain and an api_token query parameter. A public api_token may be used for GET widget calls in public JavaScript environments; a private api_token grants read/write access and must be used server-side only.
  termsOfService: https://judge.me/terms
  contact:
    name: Judge.me Support
    url: https://judge.me/api/docs
    email: support@judge.me
  version: '1.0'
servers:
- url: https://judge.me/api/v1
  description: Judge.me API v1
security:
- shopDomain: []
  apiToken: []
tags:
- name: Reviews
  description: List and create product and store reviews.
paths:
  /reviews:
    get:
      operationId: listReviews
      tags:
      - Reviews
      summary: List reviews
      description: Retrieve published reviews for the store, optionally filtered by product, rating, or published status, with pagination. If product_id is omitted, all product and store reviews are returned. The response does not include video URLs or replies to reviews.
      parameters:
      - name: shop_domain
        in: query
        required: true
        description: The store's myshopify.com domain, e.g. example.myshopify.com.
        schema:
          type: string
      - name: api_token
        in: query
        required: true
        description: Public or private Judge.me API token.
        schema:
          type: string
      - name: product_id
        in: query
        required: false
        description: Internal Judge.me product id to scope reviews to one product.
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: Page number for pagination.
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        required: false
        description: Number of reviews per page.
        schema:
          type: integer
          default: 10
      - name: rating
        in: query
        required: false
        description: Filter reviews by star rating (1-5).
        schema:
          type: integer
          minimum: 1
          maximum: 5
      responses:
        '200':
          description: A paginated list of reviews.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewList'
        '401':
          description: Missing or invalid api_token / shop_domain.
    post:
      operationId: createReview
      tags:
      - Reviews
      summary: Create a review
      description: Programmatically import or create a review for a product or the store. Requires a private api_token. Reviews created through the API cannot be marked verified or deleted via the API.
      parameters:
      - name: shop_domain
        in: query
        required: true
        description: The store's myshopify.com domain.
        schema:
          type: string
      - name: api_token
        in: query
        required: true
        description: Private Judge.me API token.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReviewRequest'
      responses:
        '200':
          description: The created review.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Review'
        '401':
          description: Missing or invalid private api_token.
        '422':
          description: Validation error in the review payload.
components:
  schemas:
    Review:
      type: object
      properties:
        id:
          type: integer
          description: Internal Judge.me review id.
        title:
          type: string
        body:
          type: string
        rating:
          type: integer
          minimum: 1
          maximum: 5
        product_external_id:
          type: string
          description: External (platform) product id the review belongs to.
        reviewer:
          $ref: '#/components/schemas/Reviewer'
        source:
          type: string
          description: Origin of the review (e.g. web, api, import).
        curated:
          type: string
          description: Curation/publish status of the review.
        published:
          type: boolean
        hidden:
          type: boolean
        verified:
          type: string
          description: Verification status of the buyer.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        pictures:
          type: array
          items:
            type: object
            properties:
              urls:
                type: object
                additionalProperties:
                  type: string
    ReviewList:
      type: object
      properties:
        current_page:
          type: integer
        per_page:
          type: integer
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
    CreateReviewRequest:
      type: object
      required:
      - name
      - email
      - rating
      properties:
        name:
          type: string
          description: Reviewer display name.
        email:
          type: string
          description: Reviewer email address.
        rating:
          type: integer
          minimum: 1
          maximum: 5
        title:
          type: string
        body:
          type: string
        platform:
          type: string
          description: Source platform, e.g. shopify.
        id:
          type: string
          description: External product id the review is for; omit for a store review.
        url:
          type: string
          description: Product URL.
        picture_urls:
          type: array
          items:
            type: string
    Reviewer:
      type: object
      properties:
        id:
          type: integer
        external_id:
          type: string
        email:
          type: string
        name:
          type: string
        phone:
          type: string
        accepts_marketing:
          type: boolean
        unsubscribed_at:
          type: string
          format: date-time
          nullable: true
        tags:
          type: string
  securitySchemes:
    apiToken:
      type: apiKey
      in: query
      name: api_token
      description: Public or private Judge.me API token passed as a query parameter.
    shopDomain:
      type: apiKey
      in: query
      name: shop_domain
      description: The store's myshopify.com domain passed as a query parameter.