Subscribe to events so Judge.me POSTs to your URL on review lifecycle events - review/created, review/updated, review/published, review/unpublished - and widget settings updates, with an HMAC signature you can verify on receipt.
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.