Skip to main content
Connecting a Shopify store to your account is one thing; letting a specific website project build on that store is another. This page covers the second half: the per-project catalog bridge that gives the AI coder agent live access to a store’s catalog so it can build commerce directly on that project’s site — custom storefronts, inventory-aware checkout funnels, and Shopify extensions.
This is distinct from the account-level headless-storefront setup in Connecting Shopify. Connecting registers a store on your account. This page is about which project uses that store, and what the AI can do once one is effective.

​
Where you wire it up

Every project exposes the same Shopify connection panel in two places — they render the identical control (ShopifyPanel), so use whichever you’re already on:

Ecommerce tab

/dashboard/[projectId]/ecommerce — sits in the v3 editor nav next to Database. The commerce home for the project, with the connection panel plus AI prompt ideas.

Project Settings

/dashboard/[projectId]/settings — the Shopify panel lives alongside the project’s other settings.
The panel shows the effective store at the top (the one this project will actually use), then a mode selector below it.

​
The three modes

A project decides which store it uses through one of three modes: Inherit is the default. Changing the mode saves immediately (there’s no separate Save button), and the effective-status line updates to show the active shop and where it came from — project override or account default.
If no store is connected to the account yet, the panel points you to /dashboard/commerce/settings/shopify to connect one first. You inherit or override from there.

​
Connecting a project-specific store

The Connect a project-specific store button runs an OAuth flow scoped to this project — handy when the store you want isn’t already connected on the account:
1

Click Connect a project-specific store

You’re prompted for the store’s permanent *.myshopify.com domain (for example, acme.myshopify.com). The domain is validated against that pattern before anything opens.
2

Authorize on Shopify

A popup runs the standard Shopify authorization. The flow uses intent_type='shopify_project_connect' so the callback knows to bind the result to this project.
3

Hiveku binds it to the project

The new connection is stored with purpose='project_override' and wired to the project through project_shopify_settings. The panel refreshes and shows the store as active with source project override.
The project-connect button needs a Shopify OAuth app registered on the account first (Settings → OAuth apps). If none exists, the panel surfaces a clear error instead of starting the flow.

​
What the AI can do once a store is effective

The moment a store is effective for the project, the AI coder agent in the v3 editor gains live catalog access — it can read your real products, collections, inventory, and installed apps, and it can scaffold a full storefront onto this project’s site. Open the AI editor at /dashboard/[projectId]/v3 and just ask. Concrete prompts to try (these are the same examples shown on the Ecommerce tab):
  • “Build a 3-step checkout funnel that pulls live inventory and hides sold-out variants.”
  • “Add a product page with reviews and a cart drawer.”
  • “Create a ‘back in stock’ waitlist tied to my Shopify products.”
Because the storefront client the agent scaffolds exposes real inventory (down to per-variant availability), the AI can build inventory-aware custom funnels — not just static product cards. For the catalog of what the agent generates, see Storefront Scaffolding.
The agent always checks connection status before generating commerce UI. If Shopify isn’t connected (or the project is set to Disabled), it will tell you to connect a store rather than guessing — no broken storefront code.

​
Under the hood

​
Effective-connection resolution

For a given (account, project) pair, resolveShopifyCredentials (src/lib/shopify/credentials.ts) resolves the effective connection with this precedence:
  1. Project override — if project_shopify_settings.override_mode = 'override' and the bound shopify_connection is not disconnected, use it (source: 'project_override').
  2. Disabled short-circuit — if override_mode = 'disabled', return null (this hides the account default for that one project).
  3. Account default — otherwise fall through to the first shopify_connections row on the account with purpose = 'account_default' and disconnected_at = null (source: 'account_default').
  4. None — if neither exists, null.
inherit isn’t a special case — it simply falls through to the account default. Resolution is memoized in a 60-second in-process cache; connect / disconnect / override changes bust it via bustShopifyCredentialsCache.

​
Per-dispatch agent context is metadata only

On every agent dispatch, /api/builder/ai/agent builds a lightweight Shopify slice via buildShopifyAgentContext (src/lib/shopify/agent-context.ts) and attaches it to the forwarded payload as context.shopifyCatalog. It is deliberately metadata only — no product data, no tokens:Keeping this payload cheap is intentional: it lands on every chat turn, so shipping product samples here would burn Storefront API quota and add latency. If credential resolution fails for any reason, the context degrades to connected: false and the agent simply won’t suggest shopify_* tools.On the agent-server side, this slice is written to data/shopify-catalog.json in the workspace (hiveku_agent_server/app/routes/agent.py), so the coder can read the connection state as a file before deciding whether to call any Shopify tools.

​
Product data is fetched on demand

Actual catalog content comes through MCP tools the agent calls only when it needs them. Those tools proxy the builder’s role-gated HTTP routes:
  • shopify_status → GET /api/builder/shopify/[projectId]/status (with ?include=catalog it also returns a sample of ~10 products + ~20 collections via Admin GraphQL).
  • shopify_admin_* → POST /api/builder/shopify/[projectId]/admin/[action].
  • shopify_scaffold_* → POST /api/builder/shopify/[projectId]/scaffold/[feature].
Authorization. Every tool call carries x-agent-secret (must match the builder’s AGENT_SERVER_SECRET). User-attributed write actions also carry x-builder-user-id, and the builder checks that user’s role (on account_memberships) before allowing an Admin write — members get a 403. When no connection is active for the project, the routes return 412.

​
The agent tools

All paths above are rooted at /api/builder/shopify/[projectId]. shopify_status is the one the agent is instructed to call first before generating any commerce UI, so it can reference real product handles.

​
What’s next

Connecting Shopify

OAuth flow, account-default vs project-override, what credentials get stored.

Storefront Scaffolding

What the AI agent generates: PDP, cart, JSON-LD, sitemap.

Adding to an existing project

Pre-flight compat check + dry-run for retrofits.

Shopify Overview

The headless architecture and the Shopify-owns / Hiveku-owns split.