> ## 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.
# Shopify Overview
> Connect a Shopify store and Hiveku scaffolds a server-rendered Next.js storefront with cart, checkout, customer accounts, reviews, and subscriptions — or wire the same catalog into any project so the AI coder agent can build commerce on it. Shopify stays the source of truth.
Hiveku's Shopify integration lets you build a **headless Next.js storefront** on top of any Shopify store. Products, inventory, payments, taxes, fulfillment, and shipping all stay in Shopify (the back-office your team already knows). Hiveku owns the storefront UI: pages, components, SEO, conversion features, customer accounts, subscriptions self-service, and reviews.
The result: an AI-search-friendly, agency-grade storefront that ships in one prompt, with no Shopify theme limitations and no custom code maintenance burden.
## Two ways Shopify shows up in Hiveku
The integration exposes the same connection at two altitudes. Both are backed by one OAuth connection model — connect once, use it either way.
Connect a store at `/dashboard/commerce/settings/shopify` and it becomes the **account default**. This is the full storefront story described on the rest of this page — server-rendered PDPs, cart, Shopify-hosted checkout, customer accounts, reviews, subscriptions, and the CRO bundle. Every project on the account inherits the connection.
Every project has an **Ecommerce tab** (`/dashboard/[projectId]/ecommerce`, next to Database in the editor nav) that binds a Shopify connection to that one project. Once a connection is effective, the AI coder agent automatically receives the catalog context and `shopify_*` tools, so you can ask it in chat to build commerce on that site — inventory-aware funnels, custom PDPs, back-in-stock waitlists.
These are not two separate integrations. The per-project tab's **Inherit** mode uses the very same account-default connection, so a store you connect once is available at both altitudes. See [Using Shopify in projects](/integrations/shopify/using-in-projects) for the project-level flow.
## Who it's for
* **DTC brands** that want a custom storefront without paying \$5–15k for a Hydrogen agency
* **Agencies** managing multiple Shopify shops who need server-rendered SEO and per-shop tuning
* **Existing Next.js projects** that want to add Shopify commerce without rewriting
## Why headless on Hiveku, not a Shopify theme
Standard Shopify themes (Liquid) and even Online Store 2.0 ship rendered HTML. They work, but you trade flexibility:
| Capability | Liquid theme | Hiveku + Shopify (this) |
| -------------------------------------------------- | ----------------------------------- | --------------------------------------------------------- |
| Server-rendered HTML on first byte | Yes | Yes |
| AI-search SEO (JSON-LD on first byte) | Partial — depends on theme | **Always**, with `aggregateRating` populated from reviews |
| Fully custom React components | Limited | Yes — any Next.js pattern |
| AI agent edits the storefront | No | Yes — the Hiveku AI ships changes via chat |
| Shopify checkout (PCI handled) | Yes | Yes |
| Customer Accounts UI you control | Limited | Yes — full server-rendered |
| Subscription self-service on a custom storefront | No (Liquid-only apps like ReCharge) | **Yes** — first wedge over the headless agencies |
| Reviews ship inline with `aggregateRating` JSON-LD | Yotpo/Loox/Stamped (Liquid-only) | **Yes** — Hiveku Reviews is headless-native |
## What you get when you connect Shopify
A single OAuth connection unlocks the whole stack. The AI agent then scaffolds whichever pieces you need:
`/products` list and `/products/[handle]` detail. Product JSON-LD with breadcrumbs and `aggregateRating` ships in HTML on first byte. Works in AI search (ChatGPT, Claude, Perplexity).
Cart drawer, persistent cart cookie, hand-off to Shopify-hosted checkout. PCI compliance stays with Shopify Payments.
Sign-in, order history, profile, addresses. OAuth via Shopify's Customer Account API — credentials never touch your server.
First-party, headless-compatible product reviews with `aggregateRating` JSON-LD, signed-link submit flow, moderation queue.
Subscribe-vs-one-time picker on PDPs, cadence dropdown, customer self-service (pause / resume / cancel) — built on Shopify's first-party Subscription Contracts API.
Free-shipping bar, stock urgency, recently viewed, trust badges, cart upsell — five conversion components auto-included, tunable per shop.
## The architectural split (important to understand)
Hiveku's Shopify integration is opinionated about a clean separation:
* **Shopify owns:** products, inventory, orders, payments, taxes, shipping, fulfillment, subscription billing, customer payment methods (PCI), webhooks for state changes.
* **Hiveku owns:** the storefront pages, cart UI, customer-account UI, reviews data, conversion components, JSON-LD SEO, automation (workflows triggered by Shopify events), CRM contacts (linked from orders), the AI-agent surface.
We deliberately do **not** mirror Shopify state into Hiveku's database (no order copies, no contract copies). Shopify is the source of truth and we render fresh from its APIs each request. This avoids the classic sync-nightmare problem and means your Shopify admin always shows what's actually true.
The exceptions to "no mirroring":
* **CRM contacts** (orders auto-upsert a contact row keyed by email — gives you LTV rollups in `crm_contacts.shopify_total_spent_cents`)
* **Reviews** (Hiveku stores them so we can serve them headless-friendly; Yotpo/Loox can't because they're Liquid-only)
* **Per-connection settings** (CRO toggles, subscription copy overrides — small config rows, not transactional state)
## Multi-shop and multi-account
Hiveku is built for agencies and operators who manage more than one shop:
* Connect one Shopify store as the **account default** — every project under that account inherits it.
* Override the connection at the project level when an agency manages multiple brands in one workspace.
* Per-shop settings for CRO, subscriptions, customer-account auth — the fashion brand and the electronics brand don't share thresholds.
The per-project **Ecommerce tab** is where you flip a project between **Inherit**, **Override**, and **Disabled**, or connect a store just for that one project. See [Using Shopify in projects](/integrations/shopify/using-in-projects).
## Hard preconditions to know
* **Shopify Payments** is required for native subscriptions (gates \~12 countries: US, CA, UK, AU, IE, NL, NZ, ES, IT, DE, FR + a few more). Outside those, subscriptions need a third-party app (ReCharge integration is a roadmap item).
* **Shopify Subscriptions** (the free first-party app) must be installed before subscriptions render. Hiveku detects + warns if it's missing.
* **Customer Account API** application must be registered in Shopify admin before the customer-account scaffold's OAuth callback works.
* **Headless-incompatible apps** (Yotpo, ReCharge, Bold, ReConvert, Liquid-only search apps) will not work on the Hiveku storefront. Hiveku ships first-party replacements for the most common ones — see [App Compatibility](#app-compatibility) below.
## Where it lives in the dashboard
| Surface | Path |
| ---------------------------------------------- | ----------------------------------------- |
| Connect / disconnect Shopify (account default) | `/dashboard/commerce/settings/shopify` |
| Per-project connection (Ecommerce tab) | `/dashboard/[projectId]/ecommerce` |
| Storefront tuning (CRO + subscription copy) | `/dashboard/commerce/settings/storefront` |
| Reviews moderation queue | `/dashboard/commerce/shopify/reviews` |
| AI ops inbox (Shopify-driven recommendations) | `/dashboard/commerce/inbox` |
## Under the hood: the per-project bridge
The **Ecommerce tab** (`/dashboard/[projectId]/ecommerce`) and the project **Settings → Shopify** panel both render the shared `ShopifyPanel`, which sets one project's effective connection.
**Modes.** The panel writes an `override_mode` of `inherit`, `override`, or `disabled`:
| Mode | Effect |
| ---------- | ------------------------------------------------------- |
| `inherit` | Use the account-default connection (or none if absent). |
| `override` | Bind this project to a specific connected store. |
| `disabled` | Opt this project out of Shopify entirely. |
**Routes.**
| Route | Purpose |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/builder/shopify/[projectId]/status` | The project's effective connection. The agent calls the same route with `?include=catalog` to pull sample products/collections. |
| `PUT /api/builder/shopify/[projectId]/settings` | Sets `override_mode` + `shopify_connection_id`. |
| `GET /api/builder/shopify/connections` | The account's connected stores (encrypted token columns are omitted). |
| `POST /api/oauth/shopify/start` | Project-scoped OAuth. "Connect a project-specific store" sends `intent_type: 'shopify_project_connect'` with `intent_data.project_id`; the callback creates a connection row with `purpose='project_override'` and binds it through `project_shopify_settings`. |
**Agent context.** Once a connection is effective, every agent dispatch for that project carries a lightweight `shopifyCatalog` object — `{ connected, shopDomain, source, scopes, toolsAvailable }` — where `source` is `account_default` or `project_override`. When `connected` is `false`, the agent must not call `shopify_*` tools.
**Agent tools.** With a connection effective, the coder agent gets:
* `shopify_status` — effective connection + sample products/collections (call before generating commerce UI).
* `shopify_admin_` — Admin API proxy (`ping`, `get_shop`, `list_products`, `list_installed_apps`, `create_product_draft`, `invalidate_cache`, `app_compat_check`).
* `shopify_scaffold_` — writes storefront code (`storefront-client`, `revalidate-route`, `cart`, `sitemap`, `customer-account`, `product-detail-route`, `reviews`, `subscriptions`); supports `{ dryRun: true }`.
* `shopify_scaffold_compat_check` — pre-flight router/tsconfig/Tailwind/collision check before scaffolding into a non-greenfield project.
* `shopify_sandbox_create`, `shopify_customer_account`, `shopify_eject_manifest`.
**Live inventory.** The scaffolded storefront client exposes `ProductVariant.quantityAvailable` (units in stock, null when untracked) alongside `availableForSale`, so the agent can build inventory-aware funnels — hide sold-out variants, show "only N left", gate a funnel step — that read fresh from the Storefront API at render time.
This is the "build ON the live store" path (custom flows on the user's own Next.js site). It is distinct from "extend Shopify" (checkout/admin extensions + Functions), which deploy to the merchant's own Shopify app.
## Next steps
OAuth flow, account-default vs project-override, multi-shop setup.
The Ecommerce tab, the catalog bridge, and how the AI coder agent builds commerce on any project site.
What the AI agent scaffolds: PDP, cart, JSON-LD, sitemap.
Subscribe-and-save: how it differs from your billing engine, what gets scaffolded.
First-party headless reviews, signed-link submit flow, JSON-LD `aggregateRating`.
Five conversion components shipped by default; how to tune per shop.
The pre-flight compat check + dry-run mode that makes retrofits clean.