Widget data API

1. How it works

Each widget has a key, for example kroonvosdemo2026widget01. You find it in the embed code in your Shopreviews account. The key gives you two public URLs:

GEThttps://cdn.shopreviews.com/widget.js GEThttps://cdn.shopreviews.com/w/{key}.json

The first is the script that draws the widget. The second is the widget's data: its settings, your score and the reviews it shows. Shopreviews rewrites that file whenever something changes. Showing a widget only reads the file, so it stays fast however busy your site is.

The key never changes. You can switch plan, layout or review sources and the embed code on your site keeps working. Only the content of the file changes.

2. Embed code

Paste this where the widget should appear. Add the script once per page, even with several widgets.

<script src="https://cdn.shopreviews.com/widget.js" async></script>
<div data-shopreviews-widget="kroonvosdemo2026widget01"></div>

The widget renders inside a Shadow DOM, so your CSS and ours do not affect each other. It loads when it scrolls near the visible part of the page.

The script sends a shopreviews:render event on the element when a widget is drawn:

document.addEventListener('shopreviews:render', (event) => {
  console.log(event.detail.key, event.detail.layout);
});

3. Embed attributes

The settings saved in your account apply by default. These optional attributes override them for one place on your site:

Example:

<div data-shopreviews-widget="kroonvosdemo2026widget01"
     data-layout="grid"
     data-limit="3"
     data-lang="de"
     data-theme="dark"></div>

4. Reading the JSON yourself

You do not need our script. The file is plain JSON, open to any site, and needs no API key.

curl https://cdn.shopreviews.com/w/kroonvosdemo2026widget01.json

An unknown, paused or deleted widget does not give an error. It answers with status 200 and this body, so check for it first:

{"off":true}

JavaScript

const res = await fetch('https://cdn.shopreviews.com/w/kroonvosdemo2026widget01.json');
const doc = await res.json();

if (!doc.off) {
  console.log(doc.summary.average, doc.summary.count);   // 4.5 60
  for (const review of doc.reviews) {
    console.log(review.rating, review.author ?? doc.i18n.anonymous, review.body);
  }
}

PHP

$json = file_get_contents('https://cdn.shopreviews.com/w/kroonvosdemo2026widget01.json');
$doc  = json_decode($json, true);

if (empty($doc['off'])) {
    printf("%.1f from %d reviews\n", $doc['summary']['average'], $doc['summary']['count']);
}

5. Sample document

This is a shortened document of a demo shop with three review sources. The complete file is at /docs/sample-widget.json. The shop and its reviews are made up.

{
  "v": 1,
  "published_at": "2026-11-12T09:30:00+00:00",
  "widget": {
    "key": "kroonvosdemo2026widget01",
    "layout": "carousel",
    "settings": {
      "accent_color": "#FB3B39",
      "theme": "light",
      "ui_language": "nl",
      "min_rating": 4,
      "limit": 6,
      "sort": "recent",
      "show_summary": true,
      "header_text": "Wat klanten over ons zeggen"
    }
  },
  "summary": {
    "average": 4.5,
    "count": 60,
    "distribution": {
      "5": 39,
      "4": 16,
      "3": 3,
      "2": 2,
      "1": 0
    },
    "providers": [
      {
        "provider": "google",
        "label": "Google Business Profile",
        "logo": "https://portal.shopreviews.com/images/providers/google.svg",
        "count": 34,
        "average": 4.5
      },
      {
        "provider": "trustpilot",
        "label": "Trustpilot",
        "logo": "https://portal.shopreviews.com/images/providers/trustpilot.svg",
        "count": 16,
        "average": 4.4
      }
    ]
  },
  "reviews": [
    {
      "id": 55,
      "provider": "google",
      "provider_label": "Google Business Profile",
      "provider_logo": "https://portal.shopreviews.com/images/providers/google.svg",
      "author": "Sanne de Wit",
      "rating": 5,
      "title": null,
      "body": "Mijn e-bike was binnen twee dagen afgesteld en klaar. Duidelijke uitleg en geen verkooppraatje.",
      "language": "nl",
      "date": "2026-11-10T14:12:00+00:00",
      "verified": true,
      "reply": "Dank je wel Sanne, veel fietsplezier!",
      "product_sku": null,
      "product_name": null
    },
    {
      "id": 56,
      "provider": "trustpilot",
      "provider_label": "Trustpilot",
      "provider_logo": "https://portal.shopreviews.com/images/providers/trustpilot.svg",
      "author": "Mark Jansen",
      "rating": 5,
      "title": "Snelle levering, goed verpakt",
      "body": "Besteld op maandag, woensdag in huis. De fiets was voor 95% gemonteerd en de handleiding klopte.",
      "language": "nl",
      "date": "2026-11-07T14:12:00+00:00",
      "verified": true,
      "reply": null,
      "product_sku": null,
      "product_name": null
    }
  ],
  "branding": false,
  "i18n": {
    "based_on": "Gebaseerd op {count} reviews",
    "verified": "Geverifieerd",
    "read_more": "Lees meer"
  },
  "i18n_all": {
    "en": {
      "based_on": "Based on {count} reviews"
    },
    "nl": {
      "based_on": "Gebaseerd op {count} reviews"
    }
  },
  "schema": null,
  "links": {
    "powered_by": "https://www.shopreviews.com/?utm_source=widget&utm_medium=referral"
  },
  "domains": [
    "kroonenvos.example"
  ]
}

6. Field reference

Top level

widget

summary

reviews[]

The document never contains e-mail addresses, order data or other private customer data.

7. Updates and caching

• A change in your account (a setting, a new review, another plan) rewrites the file within seconds.
• Our CDN and browsers may keep a copy for up to 5 minutes, so allow that long before a change is visible everywhere.
• All files are also rewritten once a night.
• If you read the file on your server, cache it for a few minutes. There is no need to fetch it on every page view.

8. Rules for your own display

• Show the "Powered by Shopreviews" label with its link when branding is true.
• Do not change ratings, texts or names.
• Show the source of each review (provider_label).
• When domains is present, use the data on those sites only.

9. Versioning

The field v is the version of the format. We may add fields without raising it, so ignore fields you do not know. If we ever remove or rename a field, v goes up and this page says so beforehand.