# Headless product reviews via API: invite queue to widget

Run product reviews on a headless storefront. Invite queue, submit and media upload, PDP aggregates, mount options, auth and webhooks. We make Idukki.

By Rohin Aggarwal · 2026-10-31

Your Hydrogen storefront shipped without the old theme app blocks. Reviews vanished with them. Orders still flow. Invites do not. Rebuild on an API path: queue the ask, accept the review, render proof in your components.

**Quick answer**

- **Theme app blocks do not travel** to a fully headless front end. Plan an API + your own UI.
- **Run an invite queue** from order or fulfilment events, with delay and suppression rules.
- **Accept text, rating and media** through authenticated submit paths; store consent with the asset.
- **Serve aggregates and review lists** to the PDP from a cached read model.
- **Mount with your components** or a thin embed where the stack allows it.

_Figure: Headless reviews loop: order event → invite → submit → moderate → PDP read → webhook fan-out._

We make Idukki. Custom and headless teams use the developer docs, API platform and partner install paths. Theme blocks alone will not cover them. KartmaX and other custom partners usually wire catalogue and order events through a partner integration. They render proof in their own storefront.

## What headless breaks in app widgets

A Shopify theme app block assumes Liquid, the theme editor and a server-rendered product template. A headless app still has products and orders. It does not have those theme hooks.

- Product Rating Stars and review list blocks never mount.
- Thank-you page app blocks need a checkout surface your stack may replace.
- JSON-LD injected by a theme block must move into your document head.
- Invite emails that keyed off the app's theme pixel need an order webhook instead.

> **Keep the reviews platform; change the delivery:** You rarely need a new vendor for headless. You need a read/write API, webhooks and components you control. Compare platforms on those three. Theme-store screenshots are a weak filter.

## Invite queue pattern

**Post-purchase invite queue**
1. **Ingest order** — Receive order created or fulfilment delivered from your commerce webhook. (Event in)
2. **Enqueue invite** — Create a pending invite keyed to order, email, line items and send-after time. (review-invites)
3. **Respect rules** — Suppress duplicates, blocked customers and products you do not ask on. (Policy)
4. **Send** — Email or SMS with a signed link to your hosted form or headless route. (Delay met)
5. **Expire or remind** — One reminder max; close the invite when it is used or stale. (Finite life)
_High-level pattern. Exact route names vary by platform; many expose a review-invites style resource._

Time the ask to delivery when you can. Asking at purchase gets empty or angry reviews. Asking two weeks late loses the moment.

## Submit + media upload

The submit path accepts rating, title, body, product id and optional media. Media usually needs a signed upload URL, then a confirm step after the file lands.

| Role | Typical job | Notes |
| --- | --- | --- |
| Invite create / list | Queue and inspect review-invites | Driven by order events; not public |
| Invite redeem | Validate signed token from the email link | Single use; binds reviewer to order |
| Review submit | Write rating + body + product ids | Authenticated or token-bound |
| Media upload | Signed PUT then attach to review | Store rights/consent with the asset |
| Moderation | Approve, reject, flag | Only approved rows hit the PDP read model |
| Aggregate read | average + count for a product | Cache; omit when count is zero |
| Review list read | Paginated reviews for a PDP | Public or CDN-cached |
| Webhook out | review.created / approved / rejected | Keep your search index and CRM in sync |

_Endpoint roles at a high level. Not a live path list; check current docs before you build._

> **Never invent aggregates in the storefront:** If the API returns no rating, render an empty state. Hard-coding 5.0 in your React component is the headless version of fake JSON-LD.

## Aggregates on the PDP

Your product page should request average, count and a first page of reviews by product id. Render stars only when count is greater than zero.

Emit AggregateRating and Review JSON-LD in the document your headless app serves. The markup must match the visible list. Validate with the [review schema validator](/tools/review-schema-validator).

_Figure: PDP read model: cached aggregate + first page of approved reviews + JSON-LD in the HTML response._

## Mount options

1. **Fully custom UI:** your React/Vue components call the read API and own CLS and design tokens.
2. **Embed runtime:** if the stack allows a script tag, mount a vendor widget by ids. See [developer embed docs](/developers).
3. **Hybrid:** custom stars in the buy box; vendor gallery for photo reviews below.

Help for framework embeds lives under [embed on headless](/help/embed-on-headless) and the custom / headless platform notes. Pick the option your performance budget allows.

## Auth and webhooks

Write paths (invites, submit, moderation) need authenticated API keys or OAuth. Public read paths for approved reviews can stay cacheable and key-light, depending on the vendor.

- Rotate keys; never ship server secrets to the browser.
- Verify webhook signatures before you enqueue side effects.
- Treat 404/410 from your endpoint as a prune signal for dead subscriptions.
- Idempotency keys on submit stop double posts when a shopper retries.

KartmaX-style custom partner installs usually push catalogue and orders into Idukki through a partner webhook path. The storefront then pulls widgets or API reads. Exact partner routes are documented per integration. Start from [API platform](/api-platform) and [developers](/developers). Do not copy blog pseudocode into production.

**Build order:** Wire order events into an invite queue. Accept authenticated submits with media. Cache approved aggregates for the PDP. Mount UI you own. Theme blocks were only a delivery detail.

### Questions headless teams ask

**Q: Can we keep using Shopify theme review blocks on Hydrogen?**

A: Not as theme app blocks. Rebuild with API reads and your own components, or load an embed the headless page supports.

**Q: What is a review-invites pattern?**

A: A queued, delayed ask tied to an order or fulfilment. Add suppressions and a signed redeem link. Names differ by vendor; the job is the same.

**Q: Where should JSON-LD live?**

A: In the HTML your server or SSR layer returns for the PDP, matching the visible reviews. Do not rely on a missing theme block to inject it.

**Q: How do we start with Idukki?**

A: Read [/developers](/developers) and [/api-platform](/api-platform), or book a [demo](/demo) for a custom partner path. Product overview: [/reviews](/reviews).

**Q: Do webhooks replace polling?**

A: Use webhooks for created, approved and rejected events so search and CRM stay current. Keep a periodic reconcile job for missed deliveries.

### Sources
- [Idukki developers](/developers) — Embed, API and webhook documentation hubs.
- [Idukki API platform](/api-platform) — REST, webhooks and auth overview.
- [Idukki Reviews](/reviews) — Collection, moderation, Q&A and Google feed product surface.
- [Idukki help: embed on headless](/help/embed-on-headless) — Framework embed notes for non-Liquid storefronts.
- [Google Search Central, Review snippet structured data](https://developers.google.com/search/docs/appearance/structured-data/review-snippet) — Visible reviews and AggregateRating honesty.

---
Canonical: https://idukki.io/blog/headless-product-reviews-api-invite-to-widget
Tags: reviews, headless, api, hydrogen, webhooks, custom-storefront