> ## 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.

# Set up your Shopify store on Hiveku

> Connect your Shopify store, scaffold the storefront, configure conversion features, customer accounts, reviews, and subscriptions — end to end. Includes everything Hiveku can do and the things it deliberately can't.

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:

1. **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).
2. **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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Click &#x22;Connect a store&#x22;">
    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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Verify the connection appears as Active">
    Back in `/dashboard/commerce/settings/shopify`, your shop should now show with a green "Active" badge.
  </Step>
</Steps>

<Note>
  **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.
</Note>

***

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

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

<Tabs>
  <Tab title="Existing Hiveku project">
    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.
  </Tab>

  <Tab title="New project">
    Create a new Next.js project from the dashboard. Once created, open it in v3. The Shopify connection is automatically available because it's account-scoped.
  </Tab>

  <Tab title="Multi-shop agency">
    If your Hiveku account has multiple Shopify stores connected, override the connection at the project level under the project's settings page. Each project can point at a different shop.
  </Tab>
</Tabs>

***

## 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

<Steps>
  <Step title="Calls `shopify_status`">
    Reads your connection state. If Shopify isn't connected, the agent stops here and tells you to connect first.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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                                                                     |
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  **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.
</Tip>

***

## Step 4: Deploy and verify

<Steps>
  <Step title="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.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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](https://search.google.com/test/rich-results) — should show as Product-eligible.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

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

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:

<Steps>
  <Step title="In Shopify admin, go to Settings → Customer accounts">
    Enable new customer accounts.
  </Step>

  <Step title="Register a Customer Account application">
    Add the redirect URI. For preview deploys: `https://<your-fly-url>/account/auth/callback`. For production: `https://yourshop.com/account/auth/callback`.
  </Step>

  <Step title="Save the client_id">
    You'll paste this into Hiveku next.
  </Step>

  <Step title="In Hiveku, set the Customer Account client_id on the connection">
    Go to `/dashboard/commerce/shopify` → **Connection settings** → enter the client\_id + redirect URI.
  </Step>
</Steps>

### 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.

***

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

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)

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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."
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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.

<Steps>
  <Step title="In the workflow builder, create a new workflow">
    Add a `Shopify: Order Created` trigger.
  </Step>

  <Step title="Add a Wait node">
    14 days is a reasonable post-purchase delay. Most merchants use 7–21 days.
  </Step>

  <Step title="Add a Send Email node">
    The email body links to a signed review URL. Use the helper:

    ```ts theme={null}
    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.
  </Step>
</Steps>

### 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

<AccordionGroup>
  <Accordion title="Storefront says &#x22;No products&#x22; but my Shopify has products">
    Most common causes:

    1. **`NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN` not set** — your project hasn't redeployed since you connected Shopify. Click Deploy.
    2. **Storefront API not enabled in your Shopify admin** — Shopify admin → Apps → Develop apps → Configure Storefront API access.
    3. **Wrong shop domain** — verify `NEXT_PUBLIC_SHOPIFY_SHOP_DOMAIN` matches what you OAuth'd into.
  </Accordion>

  <Accordion title="Cart drawer says &#x22;useCart must be used inside <CartProvider>&#x22;">
    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."
  </Accordion>

  <Accordion title="Subscribe radio button doesn't appear on PDPs">
    Three things to check (in order):

    1. Is the Shopify Subscriptions app installed in Shopify admin?
    2. Have you configured a Selling Plan on the product?
    3. Is `NEXT_PUBLIC_SHOPIFY_SUBS_ENABLED` set on your deployed site? Check `/dashboard/commerce/settings/storefront` → Subscriptions panel master toggle.
  </Accordion>

  <Accordion title="Customer account login throws CustomerNotConfiguredError">
    The Customer Account API client isn't configured for this connection. Go to `/dashboard/commerce/shopify` → Connection settings → set the client\_id + redirect URI from your Shopify admin.
  </Accordion>

  <Accordion title="Review submission link from email returns &#x22;Invalid token&#x22;">
    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).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## What's next

<CardGroup cols={2}>
  <Card title="Shopify integration overview" icon="bag-shopping" href="/integrations/shopify/overview">
    The architectural overview — what Hiveku owns vs what Shopify owns.
  </Card>

  <Card title="AI ops inbox" icon="sparkles" href="/ai/ops-inbox">
    Daily AI briefings on your Shopify activity — actionable recommendations.
  </Card>

  <Card title="Workflows" icon="bolt" href="/integrations/workflows">
    Build automations off Shopify order, review, and subscription events.
  </Card>

  <Card title="Email marketing" icon="envelope" href="/email-marketing/audiences">
    Segment customers by Shopify lifetime value, order count, and recency.
  </Card>
</CardGroup>