Set up your Shopify store on Hiveku

This guide walks you through wiring a Shopify store into a Hiveku project. It assumes you have a Hiveku account and an existing Shopify store (live or development). At the end, your project’s deployed site renders products from Shopify, with cart, customer account, reviews, and (optionally) subscriptions — all driven by the AI agent in chat. Time estimate: 15–30 minutes for the basic storefront. Subscriptions add another 15 minutes once the Shopify-side preconditions are met.

Before you start: how the integration is shaped

Two facts that drive every step in this guide:

Your product catalog stays in Shopify. Hiveku doesn’t import products into your project. The scaffolded code reads products from Shopify’s Storefront API on every page render. Add a product in Shopify admin and it appears on your deployed site within seconds (after a webhook-driven cache bust).
Hiveku owns the storefront UI. Pages, cart, components, JSON-LD SEO, customer-account screens, reviews moderation, subscriptions self-service — the AI agent scaffolds all of it as Next.js code into your project.

If you’ve used Liquid themes or Hydrogen agencies before: this is closer to “Hydrogen with an AI building it,” not “another Shopify theme.”

Step 1: Connect your Shopify store

Open Shopify settings in your Hiveku account

Go to /dashboard/commerce/settings/shopify.The connection is account-level, not project-level — every project under that account can use it. Multi-shop accounts can connect more than one store.

Click "Connect a store"

A modal asks for two inputs:

Shop domain — your permanent *.myshopify.com domain (not your custom domain). Example: acme.myshopify.com.
OAuth app — picked from the apps your Hiveku admin registered. If you only have one, it’s preselected.

Authorize on Shopify

Hiveku opens a popup at https://{shop}.myshopify.com/admin/oauth/authorize. Approve the requested scopes (read_products, write_products, read_orders, read_customers, read_themes, etc.).The popup closes automatically. Behind the scenes Hiveku exchanges the code for an Admin API token, mints a Storefront API token, encrypts both at rest, and registers webhook subscriptions for orders, products, subscriptions, and GDPR compliance topics.

Verify the connection appears as Active

Back in /dashboard/commerce/settings/shopify, your shop should now show with a green “Active” badge.

If you don’t see a Shopify OAuth app to pick from, your Hiveku admin needs to register one first. They’d go to partners.shopify.com, create a Shopify app with the right callback URL, and add client_id + client_secret under Settings → OAuth apps in Hiveku. This is a one-time setup per Hiveku account.

Step 2: Pick the project that will host your storefront

You can either use an existing project or create a new one.

Existing Hiveku project
New project
Multi-shop agency

Open the project at /dashboard/[projectId]/v3 (the v3 builder workspace). Your Shopify connection is automatically inherited at the account level — no per-project setup unless you want a different shop.

Step 3: Ask the AI agent to scaffold the storefront

In the v3 builder chat, you can use any of these prompts (the agent recognizes the intent and picks the right tool):

“Build me a shop with my Shopify products.”
“Add a product browsing page with cart and checkout.”
“Set up an online store using my Shopify catalog.”
“Make a complete shop — products, cart, customer account.”

What the agent does

Calls `shopify_status`

Reads your connection state. If Shopify isn’t connected, the agent stops here and tells you to connect first.

Calls `shopify_scaffold_compat_check`

Pre-flight check on the project shape:

Router — App Router required. Pages Router projects are hard-blocked.
Path alias — handles @/* → ./src/* (default Hiveku) AND @/* → ./* (rewrites paths automatically).
Tailwind — required for the scaffolded components to render styled.
Routing collisions — refuses to scaffold if existing dynamic routes would clash with templates.

For a fresh Hiveku project this returns compatible: true instantly. For an imported / ejected project, the agent surfaces any blockers and stops.

Calls `shopify_scaffold_product_detail_route`

The all-in-one scaffold. Writes ~12 files into your project:

File	Purpose
`src/lib/shopify/storefront-client.ts`	GraphQL client, types, cart fragment
`app/api/shopify-products/route.ts`	Server-side fetch helper
`app/api/revalidate/route.ts`	Cache-tag invalidation endpoint (webhooks call this)
`app/api/cart/route.ts`	Cart mutations
`app/products/page.tsx`	Server-rendered product list
`app/products/[handle]/page.tsx`	Server-rendered PDP with full Product JSON-LD + `aggregateRating`
`app/cart/page.tsx`	Cart page
`src/components/cart/CartContext.tsx`	`<CartProvider>` + `<CartDrawer>` + `<CartButton>` + `useCart()`
`src/components/cart/ProductVariantPicker.tsx`	Variant select + subscribe-vs-one-time toggle (auto-renders when products have selling plans)
`src/components/cro/*`	Free shipping bar, stock urgency, recently viewed, trust badges
`src/components/cro/ProductReviews.tsx`	PDP reviews component
`app/account/write-review/page.tsx`	Review submission landing

Edits your `app/layout.tsx`

The scaffolder response flags needsLayoutWrapper: true because the cart context was newly written. The agent automatically edits your root layout to wrap children in <CartProvider><CartDrawer />{children}</CartProvider>.Without this wrapper, useCart() throws on first render. The agent does this surgery itself; you don’t need to touch the file.

If you want to preview before committing, ask the agent: “Show me what would change before you write any files.” It runs the scaffolder in dry-run mode and reports the file list + any compat warnings without touching your project.

Step 4: Deploy and verify

Click Deploy in the v3 builder

Hiveku injects the right Shopify env vars automatically:

SHOPIFY_SHOP_DOMAIN, SHOPIFY_API_VERSION, SHOPIFY_ADMIN_TOKEN (server-only)
NEXT_PUBLIC_SHOPIFY_SHOP_DOMAIN, NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN, NEXT_PUBLIC_SHOPIFY_CONNECTION_ID
NEXT_PUBLIC_SHOPIFY_CRO_* and NEXT_PUBLIC_SHOPIFY_SUBS_* (CRO + subscriptions config)

No manual env-var setup is required.

Visit your deployed `/products` route

Your full Shopify catalog renders with titles, prices, images. View-source confirms the data is in HTML on first byte (visible to AI search crawlers like ChatGPT, Claude, Perplexity).

Visit a product detail page at `/products/<handle>`

Click into any product. Right-click → View Page Source. You should see:

Product title, description, price in the HTML
A <script type="application/ld+json"> Product schema block
When reviews exist: aggregateRating populated inside that schema
A BreadcrumbList JSON-LD block

Test a Google rich snippet preview at search.google.com/test/rich-results — should show as Product-eligible.

Click 'Add to cart'

Cart drawer opens. Adjust quantity, click Checkout — Shopify-hosted checkout opens with the right line items. PCI compliance, fraud detection, taxes, shipping rates all stay with Shopify.

Adds /account/login, /account/orders, profile, and addresses pages. Customer authentication uses Shopify’s Customer Account API (separate OAuth from your Admin connection — each shop owns its own auth).

Hard precondition

Your shop must have a Customer Account application registered in Shopify admin. Steps:

In Shopify admin, go to Settings → Customer accounts

Enable new customer accounts.

Add the redirect URI. For preview deploys: https://<your-fly-url>/account/auth/callback. For production: https://yourshop.com/account/auth/callback.

Save the client_id

You’ll paste this into Hiveku next.

In Hiveku, set the Customer Account client_id on the connection

Go to /dashboard/commerce/shopify → Connection settings → enter the client_id + redirect URI.

Then ask the agent

Prompt:

“Add customer account login and order history.”

The agent calls shopify_scaffold_customer_account and writes the /account/* scaffold. Sign-in buttons, order list, and profile pages all work after the next deploy.

The variant picker subscribe-vs-one-time toggle is already scaffolded in step 3. It self-disables when products have no selling plans, so it’s invisible until your shop is ready.

Hard preconditions (operational, not Hiveku)

Turn on Shopify Payments

Required for native subscriptions. Country-gated: US, CA, UK, AU, IE, NL, NZ, ES, IT, DE, FR + a few more. Shopify admin → Settings → Payments.Outside these countries, your only path today is a third-party app (ReCharge, Bold, Smartrr) which Hiveku does NOT yet integrate with.

Install the Shopify Subscriptions app

Free, first-party. Provides the recurring billing engine. Shopify admin → Apps → search “Shopify Subscriptions”.Without this, product.sellingPlanGroups is empty everywhere and the storefront subscribe toggle stays hidden.

Configure Selling Plans on your products

Hiveku doesn’t define selling plans — Shopify does. In Shopify admin under your product’s pricing options, click “Add subscription option” and configure cadence + discount.Example: “Subscribe every 30 days, 10% off.”

Add the customer-account self-service pages

Prompt: “Add subscription management to my customer account.”The agent calls shopify_scaffold_subscriptions which adds /account/subscriptions (list of contracts) and /account/subscriptions/[id] (pause / resume / cancel). Bundles the customer-account scaffold if you don’t already have it.

Optional: tune subscription copy

Visit /dashboard/commerce/settings/storefront for the subscriptions panel:

Picker heading (“Purchase options”)
One-time vs Subscribe labels
Default selection (one-time vs subscribe-first)
Savings badge text
Customer self-service toggle (off = /account/subscriptions returns 404)

Changes apply on the next deploy.

What shoppers experience

See subscribe-vs-one-time radio + cadence dropdown on the PDP (auto-renders when selling plans exist).
Cart line shows “Subscribe — every 30 days” badge.
Checkout creates a Subscription Contract on Shopify’s side.
Manage from /account/subscriptions — pause / resume / cancel inline.

Workflow automations off subscription events

Five workflow trigger node types are now in the palette (workflow builder → “Add trigger”):

Shopify: Subscription Started — anchor for thank-you / VIP-flagging
Shopify: Subscription Paused — anchor for “we miss you” re-engagement
Shopify: Subscription Cancelled — anchor for win-back email sequences
Shopify: Subscription Billing Failed — card-update reminder + ops alert
Shopify: Subscription Billing Succeeded — “your X is shipping” notifications

Filter conditions: eventTypes, connectionId, minAmountCents, maxAmountCents.

Step 7: Optional — Reviews

The <ProductReviews/> component is already scaffolded in step 3. Reviews land in moderation queue at /dashboard/commerce/shopify/reviews. JSON-LD aggregateRating populates automatically when at least one review is approved.

Collecting reviews via workflow

Reviews aren’t auto-collected; you build a workflow that sends review-request emails after orders.

In the workflow builder, create a new workflow

Add a Shopify: Order Created trigger.

Add a Wait node

14 days is a reasonable post-purchase delay. Most merchants use 7–21 days.

Add a Send Email node

The email body links to a signed review URL. Use the helper:

import { buildReviewRequestUrl } from '@/lib/shopify/reviews'

const reviewUrl = buildReviewRequestUrl({
  deployedSiteBaseUrl: 'https://yourshop.com',
  shopifyConnectionId: '...',
  accountId: '...',
  customerEmail: order.customer.email,
  productHandle: line.productHandle,
  productTitle: line.productTitle,
  orderId: order.id,
})

The token is HMAC-signed, valid for 30 days, and tied to the specific (customer, product, order) — so the submit endpoint knows it’s a verified purchase.

Moderating reviews

Pending reviews land in /dashboard/commerce/shopify/reviews with star rating, customer email, product, body excerpt.
One-click Approve / Reject / Mark as Spam.
Approved reviews go live and feed aggregateRating on the PDP.
1- and 2-star reviews auto-seed an urgent item in the AI ops inbox so you don’t miss them.

Reward automations

Build workflows that fire on Shopify: Review Approved with minRating: 5 to auto-send thank-you discounts to happy customers.

Step 8: Optional — Tune the storefront (CRO)

Visit /dashboard/commerce/settings/storefront for the conversion-rate panel. Five components are auto-included in your storefront and tunable per shop:

Component	Default	What you tune
Free shipping bar	OFF (no threshold set)	Threshold ($), currency, custom message
Stock urgency badge	ON, ≤10 units	Threshold
Recently viewed strip	ON, 5 products	Count
Trust badges (payment monograms)	ON	Toggle
Cart upsell	OFF	Toggle + minimum subtotal (Phase 2 — toggle exists, component scaffolds later)

Multi-shop accounts get a shop picker — settings are per-shop, so a fashion brand’s stock-urgency threshold of 5 doesn’t override an electronics brand’s 50. Changes apply on the next deploy.

Step 9: Optional — Build automations off Shopify events

The workflow builder now has 12 Shopify trigger node types in the palette: Order events:

Shopify: Order (any event) — fires on create AND update
Shopify: Order Created — anchor for thank-you / welcome / post-purchase upsells
Shopify: Order Updated — refunds, partial fulfillment, address changes

Review events:

Shopify: Review (any event)
Shopify: Review Submitted — alert ops on negative reviews (use maxRating: 2)
Shopify: Review Approved — recommended for “thank-you discount on 5-star” automations

Subscription events:

Shopify: Subscription (any event)
Shopify: Subscription Started
Shopify: Subscription Paused
Shopify: Subscription Cancelled — win-back sequences
Shopify: Subscription Billing Failed — #1 churn signal; auto-send card-update reminder
Shopify: Subscription Billing Succeeded

Each trigger has filter-condition fields (rating ranges, amount thresholds, product handles, connection scoping for multi-shop) so workflows fire on the right subset of events.

Step 10: Optional — Segment customers by Shopify activity

Every Shopify order auto-upserts the customer into your CRM with rollup fields:

shopify_total_spent_cents (lifetime value)
shopify_order_count
shopify_first_order_at
shopify_last_order_at
shopify_first_order_id

Build email-marketing audiences that filter on these directly. In /dashboard/marketing/email/audiences/new, the Shopify commerce filters section gives you:

Order history — Has at least one Shopify order (buyers) / No Shopify orders yet (leads)
Min/max lifetime spend — VIP segments (e.g. min $500)
Min order count — repeat buyers (e.g. 2+)
Last ordered after / before — recency windows

Combine with tag filters and lifecycle stages for compound segments.

What Hiveku can’t do (set expectations correctly)

The integration deliberately keeps Shopify as the source of truth for the merchant catalog and operations. So:

❌ Hiveku doesn’t manage products. Add, edit, delete in Shopify admin. (Exception: AI agent can create draft products via Admin API, gated on admin/owner role — but they stay drafts until you publish them in Shopify admin.)
❌ Hiveku doesn’t manage inventory. Quantities live in Shopify.
❌ Hiveku doesn’t manage orders. View / refund / fulfill in Shopify admin.
❌ Hiveku doesn’t manage shipping rates or taxes. Shopify owns these.
❌ Hiveku doesn’t process payments. Shopify Payments owns PCI; we never touch a card number.
❌ Hiveku doesn’t run the recurring-billing engine. Shopify Payments + Shopify Subscriptions charge customers on cadence; we render the storefront UI on top.
❌ Hiveku doesn’t bulk-import existing reviews from Yotpo / Loox / Stamped / Okendo. New reviews collected via Hiveku flow land in Hiveku Reviews; previously-collected ones stay where they are. Bulk-import CSV is roadmap.
❌ Hiveku doesn’t ship a Hydrogen storefront natively. It scaffolds Next.js. The shopify_eject_manifest tool generates the migration plan to Hydrogen if you want to leave; the actual AST transform is roadmap.
❌ Hiveku doesn’t change Shopify settings on your behalf. Customer Account API client config, payment-method enablement, taxes, shipping zones — all live in Shopify admin and you configure them there.
❌ Hiveku doesn’t bridge non-Shopify-Payments subscriptions. ReCharge / Bold / Smartrr / Skio are headless-incompatible with our scaffolds. They work only on Liquid themes.
❌ Hiveku doesn’t run on Pages Router. Storefronts require Next.js App Router. shopify_scaffold_compat_check will hard-block a Pages Router project.

Apps that won’t work on a headless Hiveku storefront

If your shop has any of these installed, they won’t render on the Hiveku-built site. The AI agent’s shopify_admin_app_compat_check tool detects them and recommends Hiveku-native replacements:

Installed app	Why it won’t work	Hiveku replacement
Yotpo, Loox, Stamped, Okendo	Liquid-only review widgets	Hiveku Reviews (already scaffolded)
ReCharge, Bold, Skio, Smartrr	Liquid-only subscription apps	Hiveku Subscriptions on Shopify Subscription Contracts API
ReConvert, Zipify OCU, AfterSell	Liquid-only post-purchase upsells	Hiveku cart upsell (Phase 2)
Liquid-only popup or wishlist apps	Liquid-only	Build with Hiveku components

Run the compat check via prompt: “Check my installed Shopify apps for headless compatibility.”

Things to know about deployment

Hot updates from Shopify — when you add or edit products, fire products/create, products/update, or collections/update webhooks reach Hiveku → Hiveku calls your deployed site’s /api/revalidate?tag=...&token=... → Next.js invalidates the cache. New product appears within seconds. Zero code change, zero redeploy.
Cache-tag bust manually — if a product looks stale (rare), prompt the AI agent: “My catalog looks stale, please refresh.” It calls shopify_admin_invalidate_cache to force a bust.
Preview deploys (Fly) vs production / staging (ECS) — env-var injection happens for both. Preview URLs are full-featured.
Disconnect — going back to /dashboard/commerce/settings/shopify and clicking Disconnect marks the connection inactive. The next deploy strips the Shopify env vars; the currently-running site keeps working until then.

Common pitfalls

Storefront says "No products" but my Shopify has products

Most common causes:

NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN not set — your project hasn’t redeployed since you connected Shopify. Click Deploy.
Storefront API not enabled in your Shopify admin — Shopify admin → Apps → Develop apps → Configure Storefront API access.
Wrong shop domain — verify NEXT_PUBLIC_SHOPIFY_SHOP_DOMAIN matches what you OAuth’d into.

Cart drawer says "useCart must be used inside <CartProvider>"

The layout wrapper wasn’t applied. Open app/layout.tsx and confirm children are wrapped in <CartProvider><CartDrawer/>...</CartProvider>. If the AI agent didn’t add it, ask: “Wrap my root layout in CartProvider for the cart to work.”

Review submission link from email returns "Invalid token"

Tokens expire after 30 days. If the customer opens an old email, generate a new link via a follow-up workflow run. Tokens are also invalidated if the merchant disconnects + reconnects Shopify (the encryption key changes).

Routing collision when adding Shopify to an existing project

If your project has app/products/[slug]/page.tsx (different dynamic param name), Hiveku’s compat check blocks the scaffold. Either rename your existing route to [handle] or ask the agent to scaffold under app/shop/ instead.

What’s next

Shopify integration overview

The architectural overview — what Hiveku owns vs what Shopify owns.

AI ops inbox

Daily AI briefings on your Shopify activity — actionable recommendations.

Workflows

Build automations off Shopify order, review, and subscription events.

Email marketing

Segment customers by Shopify lifetime value, order count, and recency.

​Before you start: how the integration is shaped

​Step 1: Connect your Shopify store

​Step 2: Pick the project that will host your storefront

​Step 3: Ask the AI agent to scaffold the storefront

​What the agent does

​Step 4: Deploy and verify

​Step 5: Optional — Customer accounts (sign-in + order history)

​Hard precondition

​Then ask the agent

​Step 6: Optional — Subscriptions (subscribe & save)

​Hard preconditions (operational, not Hiveku)

​What shoppers experience

​Workflow automations off subscription events

​Step 7: Optional — Reviews

​Collecting reviews via workflow

​Moderating reviews

​Reward automations

​Step 8: Optional — Tune the storefront (CRO)

​Step 9: Optional — Build automations off Shopify events

​Step 10: Optional — Segment customers by Shopify activity

​What Hiveku can’t do (set expectations correctly)

​Apps that won’t work on a headless Hiveku storefront

​Things to know about deployment

​Common pitfalls

​What’s next

Shopify integration overview

AI ops inbox

Workflows

Email marketing

Before you start: how the integration is shaped

Step 1: Connect your Shopify store

Step 2: Pick the project that will host your storefront

Step 3: Ask the AI agent to scaffold the storefront

What the agent does

Step 4: Deploy and verify

Step 5: Optional — Customer accounts (sign-in + order history)

Hard precondition

Then ask the agent

Step 6: Optional — Subscriptions (subscribe & save)

Hard preconditions (operational, not Hiveku)

What shoppers experience

Workflow automations off subscription events

Step 7: Optional — Reviews

Collecting reviews via workflow

Moderating reviews

Reward automations

Step 8: Optional — Tune the storefront (CRO)

Step 9: Optional — Build automations off Shopify events

Step 10: Optional — Segment customers by Shopify activity

What Hiveku can’t do (set expectations correctly)

Apps that won’t work on a headless Hiveku storefront

Things to know about deployment

Common pitfalls

What’s next