Shopify Overview

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.

​

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:

​

What you get when you connect Shopify

A single OAuth connection unlocks the whole stack. The AI agent then scaffolds whichever pieces you need:

​

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.

​

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

​

Where it lives in the dashboard

​

Under the hood: the per-project bridge

Developer detail — routes, data model, and agent tools

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_<action> — Admin API proxy (ping, get_shop, list_products, list_installed_apps, create_product_draft, invalidate_cache, app_compat_check).
• shopify_scaffold_<feature> — 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