openapi: 3.0.1
info:
  title: Judge.me 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.
  - name: Products
    description: Resolve external product handles or ids to internal Judge.me product ids.
  - name: Reviewers
    description: Reviewer (customer) records associated with reviews.
  - name: Widgets
    description: Ready-to-render review widget HTML.
  - name: Review Requests
    description: Trigger review request emails to customers.
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.
  /products/-1:
    get:
      operationId: lookupProduct
      tags:
        - Products
      summary: Look up internal product id
      description: >-
        Resolve an external (platform) product id or product handle into the
        internal Judge.me product id used by the reviews endpoints.
      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: Public or private Judge.me API token.
          schema:
            type: string
        - name: external_id
          in: query
          required: false
          description: External (platform) product id to resolve.
          schema:
            type: string
        - name: handle
          in: query
          required: false
          description: Product handle to resolve.
          schema:
            type: string
      responses:
        '200':
          description: The resolved product with its internal Judge.me id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductLookup'
        '404':
          description: No matching product found.
  /widgets/product_review:
    get:
      operationId: getProductReviewWidget
      tags:
        - Widgets
      summary: Get product review widget HTML
      description: >-
        Return sanitized, XSS-safe, ready-to-render HTML for the product review
        widget for a given product. Intended for use with a public api_token in
        public JavaScript environments.
      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: Public Judge.me API token.
          schema:
            type: string
        - name: product_id
          in: query
          required: true
          description: Internal Judge.me product id.
          schema:
            type: integer
      responses:
        '200':
          description: Widget HTML and supporting markup.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetResponse'
  /widgets/preview_badge:
    get:
      operationId: getPreviewBadgeWidget
      tags:
        - Widgets
      summary: Get preview badge widget HTML
      description: >-
        Return ready-to-render HTML for the preview badge showing a product's
        average star rating and review count, for product pages or collection
        thumbnails.
      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: Public Judge.me API token.
          schema:
            type: string
        - name: product_id
          in: query
          required: true
          description: Internal Judge.me product id.
          schema:
            type: integer
      responses:
        '200':
          description: Preview badge HTML.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetResponse'
  /orders/send_manual_review_request:
    post:
      operationId: sendManualReviewRequest
      tags:
        - Review Requests
      summary: Send a manual review request
      description: >-
        Trigger a review request email to a customer for a given order. Requires
        a private api_token.
      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/ReviewRequest'
      responses:
        '200':
          description: The review request was queued.
        '401':
          description: Missing or invalid private api_token.
components:
  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.
  schemas:
    ReviewList:
      type: object
      properties:
        current_page:
          type: integer
        per_page:
          type: integer
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
    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
    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
    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
    ProductLookup:
      type: object
      properties:
        product:
          type: object
          properties:
            id:
              type: integer
              description: Internal Judge.me product id.
            handle:
              type: string
            external_id:
              type: string
            title:
              type: string
    WidgetResponse:
      type: object
      properties:
        widget:
          type: string
          description: Sanitized, ready-to-render widget HTML.
    ReviewRequest:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          description: External order id.
        email:
          type: string
          description: Customer email to send the review request to.
        name:
          type: string
        platform:
          type: string
          description: Source platform, e.g. shopify.