Skip to content
NewProduct Q&A: shoppers ask on your product page and get your answers.See how it works
IdukkiIdukki
Strategy

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.

Rohin AggarwalRohin AggarwalCo-founder & CTO · Idukki.io · October 31, 2026 · 9 min read
Share
AI summaryGPTGeminiPerplexityClaudeGrok

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.

In this article
Headless reviews loop: order event → invite → submit → moderate → PDP read → webhook fan-out.
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.

Invite queue pattern

Post-purchase invite queue

  1. 01

    Ingest order

    Receive order created or fulfilment delivered from your commerce webhook.

    Event in

  2. 02

    Enqueue invite

    Create a pending invite keyed to order, email, line items and send-after time.

    review-invites

  3. 03

    Respect rules

    Suppress duplicates, blocked customers and products you do not ask on.

    Policy

  4. 04

    Send

    Email or SMS with a signed link to your hosted form or headless route.

    Delay met

  5. 05

    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.

RoleTypical jobNotes
Invite create / listQueue and inspect review-invitesDriven by order events; not public
Invite redeemValidate signed token from the email linkSingle use; binds reviewer to order
Review submitWrite rating + body + product idsAuthenticated or token-bound
Media uploadSigned PUT then attach to reviewStore rights/consent with the asset
ModerationApprove, reject, flagOnly approved rows hit the PDP read model
Aggregate readaverage + count for a productCache; omit when count is zero
Review list readPaginated reviews for a PDPPublic or CDN-cached
Webhook outreview.created / approved / rejectedKeep your search index and CRM in sync
Endpoint roles at a high level. Not a live path list; check current docs before you build.

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.

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

Mount options

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

Help for framework embeds lives under 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 and developers. Do not copy blog pseudocode into production.

Questions headless teams ask

  • Can we keep using Shopify theme review blocks on Hydrogen?

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

  • What is a review-invites pattern?

    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.

  • Where should JSON-LD live?

    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.

  • How do we start with Idukki?

    Read <a class="text-primary hover:underline" href="/developers">/developers</a> and <a class="text-primary hover:underline" href="/api-platform">/api-platform</a>, or book a <a class="text-primary hover:underline" href="/demo">demo</a> for a custom partner path. Product overview: <a class="text-primary hover:underline" href="/reviews">/reviews</a>.

  • Do webhooks replace polling?

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

Sources

  1. 1Idukki developers · Embed, API and webhook documentation hubs.
  2. 2Idukki API platform · REST, webhooks and auth overview.
  3. 3Idukki Reviews · Collection, moderation, Q&A and Google feed product surface.
  4. 4Idukki help: embed on headless · Framework embed notes for non-Liquid storefronts.
  5. 5Google Search Central, Review snippet structured data · Visible reviews and AggregateRating honesty.
#reviews#headless#api#hydrogen#webhooks#custom-storefront

More from Rohin Aggarwal