Reviews stats (star breakdown)

Overview

Get total review count plus a per-star breakdown for a single store, plus a canonical average rating and an off-platform review count. Built for hipages consumption.

Prerequisites

• A bearer token. Callable with Partner and Account tokens.

Base URL

Endpoint

GET /api/v1/reviews/stats

Authentication

• Requires a bearer token in the Authorization: Bearer <bearer-token> header.

• Who can call it: Partner and Account tokens.

• Mounted under the reviews group; no partner-only access on this specific route.

• The target store resolves by role: a location-assigned user via user_stores, an account user (assign_brand) via assignBrands, and a partner user via the full getStoreListByCompany tree walk.

• If the requested store_id is not in the caller's accessible set, it returns 403 (Store is outside your access scope.).

• Only the reachable store_id set differs per role — the response shape is identical.

Rate limit

• No rate limit.

Query parameters

• Query: store_id (integer, required) — the store to report on.
• Query: range_start (string Y-m-d, optional) — start of the windowed in_range block.
• Query: range_end (string Y-m-d, optional) — must be ≥ range_start.
• Query: review_site_id (integer, optional) — filter to a single review site (e.g. 44); also drives the per-site average.

Suppressed (suppressed_at) and soft-deleted reviews are excluded from all counts. The endpoint excludes off-platform reviews from total_reviews/star_breakdown and reported separately. Legacy reviews (is_legacy) count toward total_reviews but contribute 0 to per-star buckets.

Response

• total_reviews (int) — rating-eligible (non off-platform, non-suppressed) review count.
• star_breakdown (object) — keys "1"."5", each (int) the count of non-legacy reviews at that star value.
• average_rating (number|null) — canonical average; null when nothing is rating-eligible.
• off_platform_count (int) — off-platform (is_off_platform=true) reviews for the store, reported separately.

200 OK · 200

{
  "data": {
    "business_name": "Downtown Location",
    "range": { "start": "2026-01-01", "end": "2026-01-31" },
    "in_range": {
      "total_reviews": 142,
      "average_rating": 4.34,
      "off_platform_count": 5,
      "star_breakdown": { "1": 4, "2": 6, "3": 11, "4": 38, "5": 83 }
    },
    "lifetime": { "total_reviews": 980, "average_rating": 4.41 }
  }
}

403 Out of scope · 403

{
  "status": "error",
  "message": "Store is outside your access scope.",
  "errors": []
}

422 Validation error · 422

{
  "message": "The store id field is required.",
  "errors": {
    "store_id": ["The store id field is required."]
  }
}

Errors

Example request

curl --request GET \
  --url "https://production-api.shoutaboutus.com/api/v1/reviews/stats?store_id=123&review_site_id=44" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json'