Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt

Use this file to discover all available pages before exploring further.

​
What this is

Product reviews that work on a headless Next.js storefront. Yotpo, Loox, Stamped, and Okendo — the dominant Shopify review apps — are all Liquid-only and don’t render on a custom storefront. Hiveku ships its own review system that’s headless-native. Three pieces:
  1. <ProductReviews> server component on every PDP — rendered into the HTML on first byte, with full aggregateRating JSON-LD for Google rich snippets and AI search.
  2. Submission flow — workflow email links shoppers to /account/write-review?t=<token>. Token is signed (HMAC, 30-day TTL) so we know which order, customer, and product the review is for.
  3. Moderation queue — /dashboard/commerce/shopify/reviews. Pending submissions go here. One-click approve / reject / mark spam.

​
Why this is the wedge over Yotpo / Loox / Stamped / Okendo

  • All four are Liquid-only. They render via theme injection. Headless storefronts get nothing.
  • Their pricing starts at 19/monthandgoesto19/month and goes to 300+/month for the same merchant features.
  • None of them ship aggregateRating JSON-LD on a headless storefront because they have no theme to inject into.
Hiveku Reviews is free with the Shopify integration, ships the same JSON-LD as Yotpo would (if Yotpo could), and is the alternative our App Compatibility advisor recommends when it detects Yotpo / Loox / Stamped / Okendo on the merchant’s store.

​
What ships server-rendered

<ProductReviews> reads from the public list endpoint at render time. The PDP server component fetches reviews + computes the aggregate, embeds the result into the JSON-LD, and renders the review list: 
<!-- Visible in view-source on the deployed site -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "...",
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": 4.7,
    "reviewCount": 23,
    "bestRating": 5,
    "worstRating": 1
  },
  ...
}
</script>

<section aria-labelledby="reviews-heading">
  <h2 id="reviews-heading">Reviews</h2>
  <!-- aggregate stars, count, histogram -->
  <ul>
    <li><!-- review 1 with stars + body --></li>
    <li><!-- review 2 --></li>
    ...
  </ul>
</section>
aggregateRating only renders when at least one approved review exists. Google’s structured-data validator flags ratings with reviewCount: 0 as invalid markup, which can suppress rich snippets across the entire shop.

​
The submission flow

Reviews are collected via the workflow builder — not a separate emailing system. Build a workflow that fires after shopifyOrderCreatedTrigger, waits N days, and sends an email with a signed review link.
1

Workflow trigger fires after an order

Use shopifyOrderCreatedTrigger (already exists from Shopify integration). Configure it with onlyFirstOrders: false (you want all customers, not just new) or scope by product.
2

Wait node delays delivery

Drop in a wait node with 14 days (or whatever cadence you want). Most merchants use 7–21 days post-purchase.
3

Email step builds the review URL

The email step uses buildReviewRequestUrl() from @/lib/shopify/reviews to mint the signed link:
const url = buildReviewRequestUrl({
  deployedSiteBaseUrl: 'https://yourshop.com',
  shopifyConnectionId: connection.id,
  accountId: account.id,
  customerEmail: order.customer.email,
  productHandle: line.productHandle,
  productTitle: line.productTitle,
  orderId: order.id,
})
Example output: https://yourshop.com/account/write-review?t=<token>&handle=coffee-bag&product=Single-Origin%20Coffee%20Bag
4

Shopper opens the link, fills the form, submits

Star rating (1-5), title, body, optional name. The form posts to Hiveku’s public submit endpoint with the token.
5

Token is verified, review lands in moderation

Hiveku verifies the HMAC + TTL, decodes the embedded fields (no body fields can override identity), and inserts a pending review row.
6

Moderator approves or rejects

Notification appears in /dashboard/commerce/inbox (severity = urgent for 1-2 star reviews). Click through to /dashboard/commerce/shopify/reviews. Approve → it goes live and rich-snippet eligible. Reject → it disappears.

​
Verified-purchase flag

Reviews submitted via a token that carries an orderId are auto-flagged is_verified_purchase: true. The PDP renders a small “Verified” badge next to the rating. This is the gold-standard reviewer trust signal. Anonymous reviews (no token / token without orderId) are not supported in v1. The signed-link flow is the only submission path.

​
Moderation queue

/dashboard/commerce/shopify/reviews:
  • Tabs: Pending / Approved / Rejected / Spam
  • Per row: rating stars, customer name + email, product handle, shop (multi-shop accounts), verified-purchase badge, body excerpt
  • Inline actions: Approve / Reject / Mark Spam
  • Optimistic UI — moves the row out of the current tab on click, no full refresh
Moderating is a per-account-member action. Owner/admin/member all qualify (intentionally loose — agencies want junior staff handling the queue). Every moderation event records the acting user_id.

​
Inbox alerts

When a review lands pending, it auto-seeds a row in /dashboard/commerce/inbox:
New review: ★★★★★ from jane@example.com (verified purchase) “These coffee bags arrived right on time and the flavor was…” Approve or reject from the moderation queue.
Severity: urgent for 1-2 star reviews (you want to read those first), suggestion otherwise.

​
Workflow triggers on review events

Two trigger node types fire on review state changes:
TriggerFires on
shopifyReviewSubmittedTriggerEvery submission (any status, including pending)
shopifyReviewApprovedTriggerModerator approval (the recommended trigger for “rewards” automations)
A bare shopifyReviewTrigger matches both.

​
Filter conditions

  • minRating / maxRating — gate by star value
  • productHandles — only react to specific products
  • connectionId — multi-shop scoping
  • onlyFirstSubmission — skip resubmissions
  • onlyVerifiedPurchases — only fire on tokenized submissions
  • onlyApproved — gate on moderation (recommended for any reward automation)

​
Example automations

Thank-you discount on a 5-star approved review

Trigger: shopifyReviewApprovedTrigger Filter: minRating: 5, onlyApproved: true Action: send_email “Thanks for the kind words — here’s 15% off your next order”

Internal alert on negative reviews

Trigger: shopifyReviewSubmittedTrigger Filter: maxRating: 2 Action: notify slack #ops with reviewer email + body excerpt

UGC pull on photo reviews

Trigger: shopifyReviewApprovedTrigger (Phase 2 when photo upload ships) Action: log_crm_activity tagging contact ‘ugc_eligible’

Re-engagement to past reviewers

Use Hiveku CRM segment: last_review_submitted_at < 90 days ago Action: send_email about a new product launch

​
What gets scaffolded

Reviews ship automatically with shopify_scaffold_product-detail-route (the all-in-one storefront scaffold). For projects with a custom PDP that want to layer reviews in without re-emitting the storefront, run shopify_scaffold_reviews: 
src/components/cro/
├── ProductReviews.tsx              # server component (fetches + renders)
└── ReviewSubmitForm.tsx            # client component (submit form)

app/account/
└── write-review/page.tsx           # form host page (noindex)
The PDP template imports <ProductReviews> and feeds it the pre-fetched aggregate data so the JSON-LD reads the same numbers as the visible review list (one fetch, two consumers).

​
CRM linkage

Every review submission upserts the reviewer as a crm_contacts row (keyed by email). A future segment filter on last_review_submitted_at lets you build “thank-you” sequences targeted at reviewers without writing a new system.

​
What we did not ship (Phase 2)

  • Photo upload on reviews. Database column reserved (photos JSON); UI + S3 not wired.
  • Bulk import from Yotpo / Judge.me CSV. Schema supports it; importer not built.
  • Q&A (questions and answers on product pages). Adjacent feature, separate scope.
  • Auto-approve high-rating reviews from verified purchases. Schema supports it; UI toggle not exposed.
  • Cross-product review aggregation (a brand-level rating across all products).

​
What’s next

Workflow triggers

Build review-collection emails and reward automations.

Subscriptions

Reviews + subscriptions both share the customer-account scaffold.