Products API

Last updated: March 27, 2026

Product catalog, performance metrics, and Shopify ID lookup.

List Products

GET /api/v1/products

Query Parameters

Param	Type	Description
`search`	string	Search by product title
`status`	string	Filter by optimization status
`limit`	integer	Page size (default 20)
`offset`	integer	Pagination offset

Response (200)

{
  "products": [
    {
      "id": 456,
      "platform_id": "shopify-7125386199075",
      "title": "Organic Cotton Sweater",
      "image_url": "https://cdn.shopify.com/...",
      "optimization_status": "published",
      "last_optimized_at": "2026-03-25T10:00:00Z",
      "reviews_count": 42,
      "positive_reviews_count": 38,
      "revenue_t7d": 2500.00,
      "sessions_7d": 350,
      "conv_rate_7d": 3.2
    }
  ],
  "total": 999,
  "limit": 20,
  "offset": 0
}

Get Single Product

GET /api/v1/products/:id

Returns full product details including current optimization status and metrics.

Lookup by Shopify ID

GET /api/v1/products/lookup/:platform_id

Converts a Shopify product ID to the internal BetterReviews product ID. Use this when you have a Shopify product URL and need the ID for optimization or review endpoints.

Example

curl https://api.betterreviews.app/api/v1/products/lookup/shopify-7125386199075 \
  -H "X-API-Key: YOUR_API_KEY"

Response (200)

{
  "id": 456,
  "platform_id": "shopify-7125386199075"
}

Product Status Counts

GET /api/v1/products/status-counts

Quick overview of product optimization states across your catalog.

Response (200)

{
  "needs_review": 5,
  "published": 120,
  "not_optimized": 850,
  "failed": 2,
  "running": 1,
  "all": 999
}

Review Metrics for Products

POST /api/v1/reviews/metrics

Get review metrics for specific products by their external IDs.

Request

{
  "product_ids": ["shopify-7125386199075", "shopify-7125386199076"]
}