🌟 Trustpilot API Documentation

RESTful API for accessing Trustpilot product review data

🔑 Authentication

API Secret: All public endpoints require api-secret as the authentication parameter.

Access: These endpoints are publicly accessible for testing and integration purposes.

🔹 API v1 - Legacy

Method: GET

Purpose: Simple SKU-based review lookup

Best for: Legacy integrations, simple use cases

Rate limit: 30 requests/minute

🔸 API v2 - Stable

Method: POST

Purpose: Batch processing with validation

Best for: Production applications, structured data

Rate limit: 30 requests/minute

🚀 API v3 - Optimized

Method: POST

Purpose: High-performance batch processing

Best for: High-volume applications, real-time sync

Rate limit: 30 requests/minute

⚡ 231x Faster! Single API call for all products

🚀 Quick Start Guide

1. Choose Your API Version:

  • v1: For simple SKU lookups and legacy systems
  • v2: For production applications with structured product data
  • v3: For high-performance applications requiring maximum speed

2. Get Your API Secret:

API Secret: {Your provided api-secret}

3. Test the API:

curl -X POST "http://your-domain/api/v3/trustpilot/product-reviews/{api-secret}/batch-summaries/" \
  -H "Content-Type: application/json" \
  -d '{"products": [{"id": "123", "skus": ["sku1", "sku2"]}]}'

⚠️ Important Notes

  • Migration Path: v1 → v2 → v3 for optimal performance
  • Backward Compatibility: All versions remain supported
  • Data Format: v2 and v3 use identical request/response formats
  • Performance: v3 provides significant speed improvements for batch operations
GET

Product Reviews v1 (Legacy) Legacy

📍 Endpoint URL

GET /api/v1/trustpilot/product-reviews/{api-secret}

📝 Description

Fetches Trustpilot product reviews for specific SKUs. This is the legacy endpoint that accepts comma-separated SKUs and returns aggregated review data.

🔧 Query Parameters

sku (required): Product SKU(s) - single SKU or comma-separated list
Example: ?sku=42397086548162,42397086646466
private (optional): Use private API with authentication
Default: false
Example: ?sku=42397086548162&private=true

💡 Example Request

GET /api/v1/trustpilot/product-reviews/{api-secret}?sku=42397086548162,42397086646466

✅ Response

{
  "total_reviews": 153,
  "average_stars": 4.8,
  "api_type": "public"
}

📊 Response Codes

200 Success - Reviews retrieved successfully

400 Bad Request - Missing SKU parameter

403 Forbidden - Invalid business ID

401 Unauthorized - Authentication error (when using private API)

500 Internal Server Error - Server error occurred

POST

Product Reviews v2 (Stable) Stable

📍 Endpoint URL

POST /api/v2/trustpilot/product-reviews/{api-secret}/batch-summaries/

📝 Description

Fetches Trustpilot product reviews for multiple products in a single request. This endpoint processes multiple products with their associated SKUs and returns structured review data maintaining product relationships. The endpoint includes comprehensive payload validation to ensure data integrity.

📋 Request Body

Content-Type: application/json

Validation Rules:

  • Maximum 100 products per request
  • Each product must have an id (non-empty string) and skus (array)
  • Maximum 50 SKUs per product
  • SKUs must be non-empty strings containing only alphanumeric characters, hyphens, underscores, and dots
{
  "products": [
    {
      "id": "426547893629",
      "skus": ["42397086548162", "42397086580930", "42397086613698"]
    },
    {
      "id": "246547893623",
      "skus": ["42397086548163"]
    },
    {
      "id": "526545456786",
      "skus": ["42397086548164", "42397086580935", "42397086613666"]
    }
  ]
}

🔧 Query Parameters

private (optional): Use private API with authentication
Default: false
Example: ?private=true
format (optional): Response format for different use cases
Values: "array" (default), "hash"
Example: ?format=hash
Note: Use "hash" for faster lookups in frontend applications like Shopify

✅ Response Formats

Array Format (default):

{
  "reviews": [
    {
        "product_id": "426547893629",
        "average_stars": 4.8,
        "total_reviews": 153
    },
    {
        "product_id": "246547893623",
        "average_stars": 4.2,
        "total_reviews": 45
    }
  ]
}

Hash Format (?format=hash) - Optimized for Shopify:

{
  "reviews": {
    "426547893629": {
        "average_stars": 4.8,
        "total_reviews": 153
    },
    "246547893623": {
        "average_stars": 4.2,
        "total_reviews": 45
    }
  }
}

📊 Response Codes

200 Success - Reviews retrieved successfully

400 Bad Request - Invalid or missing JSON payload, validation errors

403 Forbidden - Invalid business ID

401 Unauthorized - Authentication error (when using private API)

500 Internal Server Error - Server error occurred

⚠️ Validation Error Examples

Missing products field:

{"error": "Missing 'products' field in payload"}

Empty products array:

{"error": "'products' array cannot be empty"}

Too many products:

{"error": "'products' array cannot contain more than 100 items"}

Missing skus field:

{"error": "Product at index 0 missing required 'skus' field"}

Too many SKUs:

{"error": "Product at index 0 'skus' cannot contain more than 50 SKUs"}

Invalid SKU format:

{"error": "Product at index 0, SKU at index 1 contains invalid characters"}
POST

🚀 Product Reviews v3 (High Performance) Optimized

📍 Endpoint URL

POST /api/v3/trustpilot/product-reviews/{api-secret}/batch-summaries/

⚡ Performance Features

🎯 Optimized for Speed

  • 231x faster than sequential processing
  • Single API call instead of multiple requests
  • 1000+ SKUs/second processing rate
  • Sub-second response times for large batches
  • Automatic deduplication of duplicate SKUs

Recommended for high-volume applications and production use.

📝 Description

The v3 endpoint is our most optimized version for batch processing multiple products. It uses advanced batching strategies to minimize API calls and maximize throughput. Perfect for high-volume applications, e-commerce platforms, and real-time product catalog synchronization.

📋 Request Body

Content-Type: application/json

Same format as v2:

{
  "products": [
    {
      "id": "426547893629",
      "skus": ["42397086548162", "42397086580930", "42397086613698"]
    },
    {
      "id": "246547893623",
      "skus": ["42397086548163"]
    }
  ]
}

🔧 Query Parameters

Same as v2 endpoint

private (optional): Use private API with authentication
Default: false
format (optional): Response format
Values: "array" (default), "hash"

✅ Enhanced Response

Includes performance metrics:

{
  "reviews": [
    {
        "product_id": "426547893629",
        "average_stars": 4.8,
        "total_reviews": 153
    }
  ],
  "performance": {
    "api_calls_made": 1,
    "processing_time_ms": 120,
    "total_skus_processed": 4,
    "skus_per_second": 33.33,
    "average_skus_per_api_call": 4.0
  }
}

🔄 Migration from v2

Easy Upgrade Path

  1. Change endpoint URL from /api/v2/ to /api/v3/
  2. Same request format and parameters
  3. Enhanced response with performance metrics
  4. Immediate performance benefits

No code changes required beyond the URL!

⚠️ Important Notes

🔍 Testing Examples

cURL Example for v3 endpoint:

curl -X POST "http://localhost:5000/api/v3/trustpilot/product-reviews/api-secret/batch-summaries/" 
  -H "Content-Type: application/json" 
  -d '{
    "products": [
      {
        "id": "426547893629",
        "skus": ["42397086548162", "42397086580930"]
      }
    ]
  }'

cURL Example for v2 endpoint:

curl -X POST "http://localhost:5000/api/v2/trustpilot/product-reviews/api-secret/batch-summaries/" 
  -H "Content-Type: application/json" 
  -d '{
    "products": [
      {
        "id": "426547893629",
        "skus": ["42397086548162", "42397086580930"]
      }
    ]
  }'

cURL Example for v1 endpoint:

curl "http://localhost:5000/api/v1/trustpilot/product-reviews/api-secret/?sku=42397086548162,42397086580930"

Powered by Trustpilot API | Built with ❤️ for seamless review integration