Reviews

A single endpoint returns the app's Shopify App Store reviews as a paginated object: "list" — GET /api/v1/apps/:app/reviews. Each row is one review (rating, body, reviewing store, developer reply); the envelope's metadata carries a summary (total + average + star distribution) and echoes back the filters you sent. Filter by rating, has_reply, or a start_date/end_date window, and sort by date or rating. Reviews Shopify has purged from the listing are held back by default — ask for them with include_archived=true.

App Store reviews

curl -G https://ranksyapp.com/api/v1/apps/01JN4HKQX0000000000000000/reviews \
  -H "Authorization: Bearer rk_live_..." \
  -d rating=5 \
  -d has_reply=true \
  -d sort=date \
  -d order=desc \
  -d per_page=25

{
  "object": "list",
  "url": "/api/v1/apps/01JN4HKQX0000000000000000/reviews",
  "page": 1,
  "per_page": 25,
  "total_count": 128,
  "has_more": true,
  "metadata": {
    "summary": {
      "total_reviews": 128,
      "avg_rating": 4.72,
      "rating_distribution": { "5": 104, "4": 14, "3": 5, "2": 2, "1": 3 }
    },
    "filters": {
      "rating": 5,
      "has_reply": true,
      "start_date": null,
      "end_date": null,
      "sort": "date",
      "order": "desc"
    }
  },
  "data": [
    {
      "id": "123456789",
      "rating": 5,
      "body": "Works exactly as described and support is fast.",
      "author": "Acme Store",
      "store_name": "Acme Store",
      "country": "US",
      "usage_duration": "About 1 year",
      "review_date": "2026-05-01",
      "has_reply": true,
      "reply": "Thanks for the kind words — glad it helped!",
      "reply_date": "2026-05-02"
    },
    {
      "id": "123456788",
      "rating": 5,
      "body": null,
      "author": null,
      "store_name": null,
      "country": "GB",
      "usage_duration": "3 months",
      "review_date": "2026-04-28",
      "has_reply": false,
      "reply": null,
      "reply_date": null
    }
  ]
}

Response shapes

The list envelope is the shared catalog object: "list" shape; each item in data is a review row. Reviews are not a date-windowed series, so coverage and currency are not present.

List envelope (object: "list")

Review row

Archived (purged) reviews

Shopify sometimes purges reviews from an app's public listing — the merchant deletes theirs, the reviewing store closes, or Shopify removes it. When that happens the review vanishes from the App Store, but Ranksy keeps the original on record and marks it archived.

Archived reviews are excluded from this endpoint by default: they are absent from data, from total_count, and from every figure in metadata.summary. That is deliberate — it keeps the API's numbers identical to the ones on your Ranksy dashboard.

Pass include_archived=true to get them back as their own labeled set:

curl -G https://ranksyapp.com/api/v1/apps/01JN4HKQX0000000000000000/reviews \
  -H "Authorization: Bearer rk_live_..." \
  -d include_archived=true

The purged set arrives under metadata.archived, never merged into data:

{
  "object": "list",
  "total_count": 128,
  "metadata": {
    "summary": {
      "total_reviews": 128,
      "avg_rating": 4.72,
      "rating_distribution": { "5": 104, "4": 14, "3": 5, "2": 2, "1": 3 }
    },
    "filters": { "rating": null, "has_reply": null, "start_date": null, "end_date": null, "sort": "date", "order": "desc" },
    "archived": {
      "summary": {
        "total_reviews": 4,
        "avg_rating": 1.75,
        "rating_distribution": { "5": 0, "4": 0, "3": 1, "2": 0, "1": 3 }
      },
      "reviews": [
        {
          "id": "123456700",
          "rating": 1,
          "body": "Stopped syncing after the update.",
          "author": "Acme Store",
          "store_name": "Acme Store",
          "country": "US",
          "usage_duration": "5 months",
          "review_date": "2026-03-14",
          "has_reply": false,
          "reply": null,
          "reply_date": null
        }
      ]
    }
  },
  "data": []
}

Pagination

The list is paginated. Use page and per_page (default 25, max 100) to walk the result set, and check has_more / total_count to know when to stop. total_count and the metadata.summary are computed after your filters, so paging never changes them within a single filtered query.

Errors

Beyond the universal 401 / 403 / 422 / 429 (see Errors), this endpoint adds nothing. There is no 409 — reviews are a scraped surface, not a Partner-integration metric — and no 400, since sort is whitelisted (date / rating): an unknown sort token, an out-of-range rating, or a bad date surfaces as 422 validation_failed.