Published API (1.0.0)
Download OpenAPI specification:
The Published API provides access to user-generated content (UGC), including product and brand reviews and ratings, for Skeepers organizations. It is designed to facilitate seamless integration with e-commerce platforms, analytics tools, and other applications by offering:
- Detailed Reviews: Access in-depth product and brand reviews with filtering, sorting, and pagination.
- Aggregated Ratings: Retrieve product ratings with breakdowns by rating levels.
- Secure Access: OAuth2.0 Authentication ensures data security and account-specific access.
- Scalable Design: Built for performance and scalability to handle high volumes of data.
This API empowers businesses to leverage user reviews and enhance customer experiences through insights and integrations.
The base URL for accessing the Published API is:
https://api.skeepers.io/verified-reviews/v1/published
Authentication is required to use the Published API. Follow the step-by-step guide below to retrieve your API credentials, obtain an access token, and use it to authenticate your requests.
1. Retrieve your API Credentials
To begin, log in to your Ratings & Reviews account: https://app.netreviews.eu/
- Navigate to the Account management > API Access menu.
- If not done already, click the Create your API account button to generate your credentials.
- Locate your API credentials (Client ID and Client secret) and keep them handy for the next step.
2. Obtain an Access Token
To obtain an access token, make a POST request to the authentication endpoint as follows:
Authentication endpoint
https://auth.skeepers.io/realms/skeepers/protocol/openid-connect/token
Header Parameters
Authorization: Basic <base64 encoded "clientId:clientSecret">
Content-Type: application/x-www-form-urlencoded
Replace <base64 encoded "clientId:clientSecret"> with the Base64-encoded value of your API credentials (Client ID and Client secret).
Request Parameters
grant_type: client_credentials
audience: verified-reviews
Example
curl -X POST "https://auth.skeepers.io/realms/skeepers/protocol/openid-connect/token" \
-H "Authorization: Basic <base64(client_id:client_secret)>" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "audience=verified-reviews"
3. Authenticate your Requests
Once you've obtained the access token, include it in the Authorization header of all your requests to the Published API as follows:
Authorization: Bearer <access_token>
Replace <access_token> with the actual access token you received from the previous step.
Great job! You are now ready to make authenticated requests to the Published API.
Let's explore the methods below!
To ensure fair usage and optimal performance for all users, the Published API implements rate limiting on all endpoints.
Rate Limits:
- 20 requests per second (maximum burst rate)
- 400 requests per minute (sustained rate)
Exceeding Rate Limits:
If you exceed the rate limit, you will receive a 429 Too Many Requests response. We recommend implementing exponential backoff in your application to handle these responses gracefully.
Response Headers:
The API returns the following headers to help you track and manage rate limits:
| Header | Description |
|---|---|
RateLimit-Limit |
Allowed limit in the timeframe. |
RateLimit-Remaining |
Number of available requests remaining. |
RateLimit-Reset |
The time remaining, in seconds, until the rate limit quota is reset. |
X-RateLimit-Limit-Second |
The time limit, in number of seconds. |
X-RateLimit-Limit-Minute |
The time limit, in number of minutes. |
X-RateLimit-Remaining-Second |
The number of seconds still left in the time frame. |
X-RateLimit-Remaining-Minute |
The number of minutes still left in the time frame. |
Retry-After |
This header appears on 429 errors, indicating how long the upstream service is expected to be unavailable to the client. |
Need Higher Limits?
If your use case requires higher rate limits, custom limits can be configured on a per-client basis. Please contact our support team to discuss your requirements and we'll work with you to establish appropriate limits for your needs.
Given our OAuth2.0 authentication system and rate limiting implementation, we recommend a specific integration pattern to optimize performance and ensure reliable data access.
Recommended Integration Pattern:
For most use cases, we recommend pulling review data into your own system rather than making direct API calls from your backend. This approach provides better performance, reliability, and user experience.
1. Initial Full Synchronization
Start by performing a complete data pull to populate your local system:
# First request - get initial batch
GET /products/reviews?limit=200&sort=publish_date
# Use cursor in Link header to know if there are more pages and continue until all data is retrieved
GET /products/reviews?cursor=eyJpZCI6MTIzfQ&limit=200&sort=publish_date
GET /products/reviews?cursor=eyJpZCI6NDU2fQ&limit=200&sort=publish_date
# ... continue until no more pages
2. Periodic Updates
After the initial sync, implement periodic updates to capture new reviews. The frequency can be determined based on your business needs while respecting our rate limits:
# Get newest reviews first, sorted by publish date descending
GET /products/reviews?limit=200&sort=publish_date&desc=publish_date
# Continue pagination until you reach reviews you already have in your system
GET /products/reviews?cursor=eyJpZCI6MTIzfQ&limit=200&sort=publish_date&desc=publish_date
# ... stop iterating once you encounter a review already in your local system
Benefits of This Approach:
- Performance: Faster response times for your users
- Reliability: Reduced dependency on real-time API availability
- Flexibility: Full control over data presentation and caching
- Rate Limit Compliance: Efficient use of API calls within our limits
Future Frontend Access:
For clients requiring direct frontend API access, we plan to introduce a dedicated public endpoint with specific rate limiting designed for client-side usage. This endpoint will complement the current server-to-server API.
Reporting reviews capacity
The API does not allow reporting reviews directly. You need to implement the reporting functionality in your own system and then report the reviews directly in our backoffice or contact our support team for assistance.
Most endpoints in the Published API use cursor-based pagination for efficient navigation through large result sets.
How it works:
- Results are returned page by page using opaque cursor tokens
- Navigate forward and backward using cursors from the
Linkresponse header - Cursors maintain your query context (filters, sorting) automatically
Getting started:
- First request: Call any paginated endpoint without a cursor parameter
- Next pages: Extract the cursor from the
Linkheader (rel="next") and use it in your next request - Previous pages: Use the cursor from
rel="prev"to navigate backward
Important rules:
- Cursors must be used with the same query parameters (filters, sorting) as the original request
- Changing filters or sorting requires starting a new pagination sequence
- Not all endpoints use pagination - check individual endpoint documentation
Example workflow:
# First request
GET /products/reviews?limit=10&sort=review_date
# Response includes Link header:
Link: <...?cursor=eyJpZCI6MTIzLCJ0aW1lc3RhbXAiOiIyMDI0LTA2LTI0VDE1OjEyOjMxWiJ9&limit=10&sort=review_date>; rel="next"
# Next request
GET /products/reviews?cursor=eyJpZCI6MTIzLCJ0aW1lc3RhbXAiOiIyMDI0LTA2LTI0VDE1OjEyOjMxWiJ9&limit=10&sort=review_date
For detailed parameter information, see the cursor and limit query parameters in each endpoint.
Search engines and AI assistants increasingly reward pages that expose their user-generated content as machine-readable structured data. Star ratings and reviews surfaced as JSON-LD are what power Google rich snippets (the star ratings shown directly in search results) and what lets AI crawlers (ChatGPT, Claude, Perplexity, …) read and cite your content — a discipline often called GEO (Generative Engine Optimization).
The catch: many of these bots index your initial HTML and does not run efficently your page's JavaScript. Best practices for SEO/GEO therefore call for the structured data to be present in the server-rendered HTML, not assembled client-side.
The Structured Data endpoints close that gap. They return ready-to-embed JSON-LD that you place in your server-rendered HTML, so the content is there the moment a crawler arrives — no SDK, no client-side assembly.
Today this is available for product reviews via GET /products/structured-datas.
Benefits
- One call, ready-to-use markup. A single request returns complete, schema.org-compliant JSON-LD you can drop straight into the page — no SDK to install and no client-side data shaping.
- Traditional SEO and GEO at once. The same markup feeds Google rich snippets and makes your reviews discoverable to AI assistants.
- Visible before JavaScript runs. Delivered server-side, the structured data is part of the initial HTML response, so crawlers that don't execute scripts still see it.
Usage best practices
These endpoints are built for server-side SEO/GEO, your end users don't need that data. it's not made for per-visitor calls. Following these rules keeps your pages fast and your usage well within Skeepers rate limits:
- Cache the response. Store the markup with your page (alongside your catalog, in your CMS, or in a CDN) and refresh it on a schedule. Do not call the API on every page render.
- Serve it for indexing, not live traffic. The goal is simply to have the JSON-LD present in the server-rendered HTML when a crawler fetches the page. Limit the call by User-Agent.
- Respect rate limits. See Rate Limiting (5 req/s, 100 req/min) and the Recommended usage pattern — pull and cache, don't poll.
⚠️ Avoid duplicate structured data
If you already embed our product widget on your pages, it ships with its own built-in Rich Snippets (JSON-LD) integration. Serving both the widget's structured data and this API's output on the same page would expose duplicate Product/AggregateRating markup to crawlers, which search engines may flag as duplicate content.
Before implementing this API, turn off the widget's built-in integration in the back-office. From the Display reviews menu, open Integrate my widgets, edit your Product Widget, expand the Advanced settings panel and switch off Activate the Rich-Snippets.
This API only works for JSON-LD structured data for now, but if you want to serve microdata or RDFa instead, you can call the endpoint, get the JSON-LD blocks, and transform them to your preferred format.
### Serving structured data only to SEO/GEO bots
Detect them from the request's `User-Agent` header and inject the JSON-LD server-side when a known SEO or AI bot is requesting the page; for regular users, skip it (your normal review widget keeps serving them).
A few representative user agents to match (case-insensitive substring is enough):
| Purpose | User-Agent contains |
|---------|---------------------|
| Google (SEO) | `Googlebot` |
| Bing (SEO) | `bingbot` |
| OpenAI / ChatGPT | `GPTBot`, `OAI-SearchBot`, `ChatGPT-User` |
| Anthropic / Claude | `ClaudeBot`, `Claude-User` |
| Perplexity | `PerplexityBot` |
```js
// Express-style example: add the JSON-LD to the HTML only for known bots
const BOT_PATTERN = /googlebot|bingbot|gptbot|oai-searchbot|chatgpt-user|claudebot|claude-user|perplexitybot/i;
if (BOT_PATTERN.test(req.headers['user-agent'] || '')) {
const jsonLd = await getCachedStructuredData(productVariationId); // your cached copy
html = html.replace('</head>', `${jsonLd}</head>`);
}
Keep the bot list under review — crawlers come and go, and you can always serve the markup to everyone if you prefer the simpler setup.
Linking to your on-page Product schema
The product blocks describe reviews about a product, not the product itself — you keep your own on-page Product schema. The two are stitched together by a shared identifier: every block we return sets itemReviewed.@id to the exact value you pass in the canonical_url query parameter. Set the @id of your on-page Product schema to that same URL and Google merges them into a single rich result.
The
@idin yourProductschema must exactly match thecanonical_urlyou send to the endpoint.
GET /products/structured-datas returns up to three schema.org blocks, all scoped to one product:
AggregateRating— the product's average score and review count.Review— individual customer reviews.Review(summary) — the AI-generated summary of all reviews, authored by your organization.
Choosing a response format
The Accept request header selects how the blocks are returned:
Accept value |
Response body |
|---|---|
application/ld+json |
A JSON object keyed by block (ratings, reviews, reviewSummary). Use this when you build the page markup yourself. |
text/javascript |
A text body where each block is already wrapped in its own <script type="application/ld+json"> tag. Drop it straight into your HTML. |
Any other Accept value returns 406 Not Acceptable.
Integrating application/ld+json — read each block from the JSON object and render it inside a <script type="application/ld+json"> tag in your page's HTML:
<script type="application/ld+json">
{ "@context": "https://schema.org", "@type": "AggregateRating", "ratingValue": 4.3, "reviewCount": 12, "itemReviewed": { "@id": "https://www.example.com/p/blue-widget" } }
</script>
Integrating text/javascript — the response is already a set of <script> tags (one per block, each with a stable id); inject the body as-is into the server-rendered HTML:
<script type="application/ld+json" id="skp-jsonld-aggregaterating">{"@context":"https://schema.org","aggregateRating":{"@type":"AggregateRating","ratingValue":4.3,"reviewCount":12}}</script>
<script type="application/ld+json" id="skp-jsonld-reviews">{"@context":"https://schema.org","review":[ ... ]}</script>
<script type="application/ld+json" id="skp-jsonld-reviewsummary">{"@context":"https://schema.org","review":[ ... ]}</script>
Get product ratings and review summaries
Retrieve comprehensive product information including aggregated ratings, AI-generated review summaries, and quality criteria data.
Use this endpoint to:
- Display star ratings and rating breakdowns on product pages
- Show AI-generated review summaries to customers
- Access quality criteria scores (if enabled in your account)
Pagination: This endpoint supports cursor-based pagination. See the Pagination section for details.
Note: Products are identified by product_variation_id. For GTIN-based lookups, use the /products/ratings endpoint instead.
Authorizations:
query Parameters
| cursor | string Example: cursor=eyJpZCI6MTIzLCJ0aW1lc3RhbXAiOiIyMDI0LTA2LTI0VDE1OjEyOjMxWiJ9 Cursor for navigating through paginated results page by page, both forward and backward. Navigation Flow:
Important Rules:
Example: |
| limit | integer [ 1 .. 200 ] Default: 10 Example: limit=10 Number of items to return per page. Constraints:
Note: The limit must remain consistent when using cursors for navigation. |
| sort | string Example: sort=review_date,review_rate Field(s) to sort results by, separated by commas for multiple fields. Sorting Rules:
Validation:
Common sortable fields:
|
| desc | string Example: desc=review_date,review_rate Specify which fields should be sorted in descending order. By default, all sorting is ascending. Usage Rules:
Validation:
Examples:
|
| product_variation_id | string Product's unique identifier. String separated by commas for multiple values. |
Responses
Response samples
- 200
- 400
- 401
- 500
[- {
- "ratings": {
- "average": 4.5,
- "count_total": 127,
- "count_5": 89,
- "count_4": 23,
- "count_3": 10,
- "count_2": 3,
- "count_1": 2
}, - "review_summary": {
- "content": "Customers love the build quality and performance, with many praising the excellent customer service. Some minor concerns about delivery times.",
- "last_updated_at": "2024-06-24T15:12:31Z"
}, - "product_variation_id": "PRODUCT-ABC-123",
- "website_id": "55d5588-5454s-55d5-1225-12558s5525",
- "extras": [
- {
- "type": "rate",
- "display_name": "QUALITY",
- "label": "Quality",
- "rate": {
- "average": 4.8,
- "count": 95
}
}
]
}
]Get individual product reviews with detailed filtering
Retrieve individual product reviews with comprehensive filtering options for building review displays, analytics, and customer insights.
Use this endpoint to:
- Build paginated review listings on product pages
- Filter reviews by rating, date, verification status, or content
- Export review data for analysis or backup
- Create custom review displays with media and author information
Advanced filtering: Supports multiple product identifiers (GTIN, SKU, MPN) and various date ranges for precise data retrieval.
Pagination: This endpoint supports cursor-based pagination. See the Pagination section for details.
Authorizations:
query Parameters
| cursor | string Example: cursor=eyJpZCI6MTIzLCJ0aW1lc3RhbXAiOiIyMDI0LTA2LTI0VDE1OjEyOjMxWiJ9 Cursor for navigating through paginated results page by page, both forward and backward. Navigation Flow:
Important Rules:
Example: |
| limit | integer [ 1 .. 200 ] Default: 10 Example: limit=10 Number of items to return per page. Constraints:
Note: The limit must remain consistent when using cursors for navigation. |
| sort | string Example: sort=review_date,review_rate Field(s) to sort results by, separated by commas for multiple fields. Sorting Rules:
Validation:
Common sortable fields:
|
| desc | string Example: desc=review_date,review_rate Specify which fields should be sorted in descending order. By default, all sorting is ascending. Usage Rules:
Validation:
Examples:
|
| product_variation_id | string Product's unique identifier. String separated by commas for multiple values. |
| product_ean | string GTIN/EAN code of the product(s). String separated by commas for multiple values. |
| product_mpn | string Manufacturer Part Number, a unique product identifier from the manufacturer. Can be a single value or a list of value separated by comma. |
| product_jan | string GTIN/JAN code of the product(s). String separated by commas for multiple values. |
| order_reference | string Reference linked to the purchase order. String separated by commas for multiple values. |
| product_upc | string GTIN/UPC code of the product(s). String separated by commas for multiple values. |
| product_sku | string Stock Keeping Unit of the product(s). String separated by commas for multiple values. |
| review_rate | Array of integers Items Enum: 1 2 3 4 5 Filter reviews by rating (1-5). |
| publish_date.$KEYWORD | string <date-time> Example: publish_date.$KEYWORD=2024-01-01T00:00:00Z Filter reviews by their publication date using date range operators. Available operators:
Format: Use ISO 8601 format: Examples:
|
| review_date.$KEYWORD | string <date-time> Example: review_date.$KEYWORD=2024-01-01T00:00:00Z Filter reviews by the date when customers originally wrote the review. Available operators:
Common use cases:
|
| order_date.$KEYWORD | string <date-time> Example: order_date.$KEYWORD=2024-01-01T00:00:00Z Filter reviews by the original purchase order date. Available operators:
Business use cases:
|
| search | string Search term to filter reviews. This search term will be applied on both the review content and the moderation text. |
| incentivization | string Enum: "none" "gifted" "compensated" "spontaneous" If the review was incentivized. Gifted meaning the product was gifted to the consumer in exchange for a review. Compensated meaning the product was bought by the consumer but the review was still compensated with monetary value. |
| syndicated_review | boolean If the review was syndicated, meaning if was not deposited on this account but on the same product on another account. |
Responses
Response samples
- 200
- 400
- 401
- 500
[- {
- "review_id": "67d7b591-40a2-7ab4-1925-0b2db7753c90",
- "author_firstname": "John",
- "author_lastname": "Doe",
- "is_personal_data_disclosed": true,
- "locale": "fr",
- "review_date": "2024-06-24T15:12:31Z",
- "review_content": "Great product!",
- "review_rate": 5,
- "publish_date": "2024-06-24T15:12:31Z",
- "order_date": "2024-06-24T15:12:31Z",
- "order_reference": "1527455",
- "product_variation_id": "1527455",
- "product_ean": "9520001112225",
- "product_upc": "012345678905",
- "product_jan": "4901234567897",
- "product_sku": "XYZ-12345",
- "product_mpn": "00638NAGPE",
- "product_brand": "Nintendo",
- "product_name": "Nintendo Switch",
- "order_id": "1527455",
- "is_verified": true,
- "medias": [
- {
- "type": "IMAGE",
}
], - "incentivization": "gifted",
- "syndicated_review": true,
- "syndicated_review_source": "Nintendo (NL)",
- "translated_review": {
- "bg": "Страхотен продукт!",
- "cs": "Skvělý produkt!",
- "de": "Großartiges Produkt!",
- "el": "Εξαιρετικό προϊόν!",
- "en": "Great product!",
- "es": "Gran producto!",
- "fr": "Très bon produit!",
- "it": "Ottimo prodotto!",
- "nl": "Geweldig product!",
- "pl": "Świetny produkt!",
- "pt": "Ótimo produto!",
- "sk": "Odličen izdelek!",
- "tr": "Harika ürün!"
}, - "moderations": [
- {
- "comment": "Merci beaucoup pour votre commentaire.",
- "date": "2025-05-28T15:30:00.000Z",
- "origin": "www.mywebsite.com",
- "origin_type": "moderator",
- "translated_comment": {
- "bg": "Благодарим за коментара!",
- "cs": "Děkujeme za komentář!",
- "de": "Vielen Dank für Ihren Kommentar!",
- "el": "Σας ευχαριστούμε για το σχόλιό σας!",
- "en": "Thank you for your comment!",
- "es": "¡Gracias por tu comentario!",
- "fr": "Merci pour votre commentaire!",
- "it": "Grazie per il tuo commento!",
- "nl": "Bedankt voor je reactie!",
- "pl": "Dziękujemy za komentarz!",
- "pt": "Obrigado pelo seu comentário!",
- "sk": "Hvala za komentar!",
- "tr": "Yorumunuz için teşekkürler!"
}
}
], - "extras": {
- "QUALITY": {
- "display_name": "PRICE",
- "label": "Price",
- "type": "I1",
- "value": 5
}, - "REVIEW_TITLE": {
- "display_name": "REVIEW_TITLE",
- "label": "Title of the review",
- "type": "S",
- "value": "Really good product"
}
}
}
]
Get aggregated product ratings by GTIN or product ID
Retrieve aggregated rating statistics for multiple products simultaneously. Ideal for catalog integrations and bulk rating lookups.
Use this endpoint to:
- Display ratings on category pages or search results
- Bulk update your product catalog with rating data
- Get ratings by GTIN codes for product matching
- Aggregate ratings across product variations
Key features:
- No pagination - returns all requested products in a single response
- Supports up to 200 products per request
- Choose aggregation by GTIN or product_variation_id
- Perfect for e-commerce catalog integrations
Authorizations:
query Parameters
| type required | string Enum: "product_ean" "product_variation_id" Type of aggregation for your ratings. Retrieve ratings by GTIN or aggregate rating at the parent level to regroup all the values per product variation id. |
| value required | string The identifier of the product you want to get ratings for. Either a list of product_variation_id or a list of GTINs. Maximum number of values is 200. String separated by commas for multiple values. |
| sort | string Example: sort=review_date,review_rate Field(s) to sort results by, separated by commas for multiple fields. Sorting Rules:
Validation:
Common sortable fields:
|
| desc | string Example: desc=review_date,review_rate Specify which fields should be sorted in descending order. By default, all sorting is ascending. Usage Rules:
Validation:
Examples:
|
Responses
Response samples
- 200
- 400
- 401
- 500
[- {
- "product_variation_id": "PRODUCT-REF-03",
- "product_ean": "GTIN-EAN",
- "average": 4.76,
- "count_total": 43,
- "count_5": 37,
- "count_4": 4,
- "count_3": 1,
- "count_2": 0,
- "count_1": 1,
- "extras": [
- {
- "count": 20,
- "average": 3.45,
- "label": "QUALITY"
}
]
}
]Get JSON-LD structured data for rich snippets
Return ready-to-embed JSON-LD (AggregateRating, Review, and the AI review summary) for a single product, so your ratings and reviews can power Google rich snippets and AI-crawler discovery.
The Accept header selects the response format: application/ld+json returns a JSON object keyed by block; text/javascript returns the blocks already wrapped in <script type="application/ld+json"> tags.
Every returned block links back to your on-page Product schema through itemReviewed.@id, which is set to the canonical_url you pass in.
For the full explanation — how to link your Product schema, how to integrate each format into your page, caching, bot-only delivery, and rate limits — see the Structured Data (Rich Snippets) section.
Authorizations:
query Parameters
| product_variation_id required | string Example: product_variation_id=PRODUCT-REF-03 The unique identifier of the product to render structured data for. Must not contain whitespace. Several variations can be combined into one product's structured data by passing a comma-separated list (e.g.
|
| canonical_url required | string <uri> Example: canonical_url=https://www.example.com/p/blue-widget The canonical URL of the product page. It is used verbatim as |
| filters | Array of strings Items Enum: "aggregate_rating" "reviews" "review_summary" Subset of blocks to return, separated by commas (e.g. |
| reviews_limit | integer [ 1 .. 100 ] Default: 5 Example: reviews_limit=5 Maximum number of |
header Parameters
| Accept required | string Enum: "application/ld+json" "text/javascript" Selects the response format:
Any other value returns |
Responses
Response samples
- 200
- 400
- 401
- 406
- 500
{- "ratings": {
- "aggregateRating": {
- "@type": "AggregateRating",
- "ratingValue": 4.3,
- "reviewCount": 12,
- "bestRating": 5,
- "worstRating": 1,
}
}, - "reviews": {
- "review": [
- {
- "@type": "Review",
- "reviewBody": "Great product, exactly as described!",
- "datePublished": "2024-06-24T15:12:31Z",
- "reviewRating": {
- "@type": "Rating",
- "ratingValue": 5,
- "bestRating": 5,
- "worstRating": 1
}, - "author": {
- "@type": "Person",
- "name": "John D."
},
}
]
}, - "reviewSummary": {
- "review": {
- "@type": "Review",
- "reviewBody": "Customers love the build quality and value, with occasional notes on delivery times.",
- "datePublished": "2024-06-24T15:12:31Z",
- "author": {
- "@type": "Organization",
- "name": "Skeepers"
},
}
}
}Get brand and shop reviews
Retrieve reviews about your brand or individual shops with advanced filtering for reputation management and customer feedback analysis.
Use this endpoint to:
- Display brand reviews on your website or app
- Monitor shop-specific feedback across multiple locations
- Filter reviews by verification status and personal data disclosure
- Build custom review management interfaces
Pagination: This endpoint supports cursor-based pagination. See the Pagination section for details.
Authorizations:
query Parameters
| cursor | string Example: cursor=eyJpZCI6MTIzLCJ0aW1lc3RhbXAiOiIyMDI0LTA2LTI0VDE1OjEyOjMxWiJ9 Cursor for navigating through paginated results page by page, both forward and backward. Navigation Flow:
Important Rules:
Example: |
| limit | integer [ 1 .. 200 ] Default: 10 Example: limit=10 Number of items to return per page. Constraints:
Note: The limit must remain consistent when using cursors for navigation. |
| sort | string Example: sort=review_date,review_rate Field(s) to sort results by, separated by commas for multiple fields. Sorting Rules:
Validation:
Common sortable fields:
|
| desc | string Example: desc=review_date,review_rate Specify which fields should be sorted in descending order. By default, all sorting is ascending. Usage Rules:
Validation:
Examples:
|
| search | string Search term to filter reviews. This search term will be applied on both the review content and the moderation text. |
| is_verified | boolean Review is verified or not. |
| is_personal_data_disclosed | boolean Whether the author has agreed to share personal data or not. |
| shop_key | string Search review by shop key of the brand. Can be a single value or a list of value separated by comma. |
| review_rate | Array of integers Items Enum: 1 2 3 4 5 Filter reviews by rating (1-5). |
| linked_to_shop | boolean The linked_to_shop filter allows you to retrieve the reviews that are linked to a shop for a brand. Using false will return only reviews that are not linked to shops. |
Responses
Response samples
- 200
- 400
- 401
- 500
[- {
- "review_id": "67d7b591-40a2-7ab4-1925-0b2db7753c90",
- "order_reference": "1527455",
- "shop_key": "B001",
- "review_content": "Great merchant!",
- "author_lastname": "Doe",
- "review_rate": 5,
- "incentivization": "gifted",
- "locale": "fr",
- "is_verified": true,
- "order_date": "2024-06-24T15:12:31Z",
- "review_date": "2024-06-24T15:12:31Z",
- "is_personal_data_disclosed": true,
- "author_firstname": "John",
- "publish_date": "2024-06-24T15:12:31Z",
- "website_id": "55d5588-5454s-55d5-1225-12558s5525",
- "moderations": [
- {
- "comment": "Merci beaucoup pour votre commentaire.",
- "date": "2025-05-28T15:30:00.000Z",
- "origin": "www.mywebsite.com",
- "origin_type": "moderator"
}
], - "extras": {
- "REVIEW_TITLE": {
- "display_name": "REVIEW_TITLE",
- "label": "Title of the review",
- "type": "S",
- "value": "Really good product"
}
}
}
]Get brand and shop rating, review summaries and certificate link
Retrieve aggregated rating statistics and performance metrics for your brand and individual shop locations.
Use this endpoint to:
- Display overall brand rating badges on your website
- Monitor shop performance across different locations
- Access historical rating trends (1-year and 5-year data)
- Get first review dates and total review counts since account creation
- Access certificate link for Verified Reviews badge display
Pagination: This endpoint supports cursor-based pagination. See the Pagination section for details.
Authorizations:
query Parameters
| cursor | string Example: cursor=eyJpZCI6MTIzLCJ0aW1lc3RhbXAiOiIyMDI0LTA2LTI0VDE1OjEyOjMxWiJ9 Cursor for navigating through paginated results page by page, both forward and backward. Navigation Flow:
Important Rules:
Example: |
| limit | integer [ 1 .. 200 ] Default: 10 Example: limit=10 Number of items to return per page. Constraints:
Note: The limit must remain consistent when using cursors for navigation. |
| sort | string Example: sort=review_date,review_rate Field(s) to sort results by, separated by commas for multiple fields. Sorting Rules:
Validation:
Common sortable fields:
|
| desc | string Example: desc=review_date,review_rate Specify which fields should be sorted in descending order. By default, all sorting is ascending. Usage Rules:
Validation:
Examples:
|
| shop_key | string Search review by shop key of the brand. Can be a single value or a list of value separated by comma. |
| linked_to_shop | boolean The linked_to_shop filter allows you to retrieve the reviews that are linked to a shop for a brand. Using false will return only reviews that are not linked to shops. |
Responses
Response samples
- 200
- 400
- 401
- 500
[- {
- "five_year": {
- "average": 4.76,
- "count_5": 37,
- "count_4": 4,
- "count_3": 1,
- "count_2": 0,
- "count_1": 1
}, - "shop_key": "B001",
- "count_total_since_creation": 43,
- "one_year": {
- "average": 4.76,
- "count_5": 37,
- "count_4": 4,
- "count_3": 1,
- "count_2": 0,
- "count_1": 1
}, - "oldest_review_publish_date": "2024-06-24T15:12:31Z",
- "website_id": "55d5588-5454s-55d5-1225-12558s5525",
}
]