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

# Using Shopify in a Project

> Wire a connected Shopify store into a single website project so the AI coder agent can build commerce on that project's own site — custom storefronts and inventory-aware funnels with live catalog access.

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.

<Note>
  This is distinct from the account-level headless-storefront setup in [Connecting Shopify](/integrations/shopify/connecting). 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.
</Note>

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

<CardGroup cols={2}>
  <Card title="Ecommerce tab" icon="store">
    `/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.
  </Card>

  <Card title="Project Settings" icon="gear">
    `/dashboard/[projectId]/settings` — the Shopify panel lives alongside the project's other settings.
  </Card>
</CardGroup>

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:

| Mode                               | What it does                                           | When to use                                                         |
| ---------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
| **Inherit from account**           | Use the account-default Shopify store, if any.         | The common case — one account, one brand, one store.                |
| **Override with a specific store** | Pick a specific connected store for this project only. | Agencies running multiple brands in one workspace.                  |
| **Disabled**                       | Opt this project out of Shopify entirely.              | A marketing site or blog in an otherwise Shopify-connected account. |

`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**.

<Info>
  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.
</Info>

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

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

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

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

<Warning>
  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.
</Warning>

## 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](/integrations/shopify/storefront).

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

***

## Under the hood

<Accordion title="How the catalog bridge actually works (for developers)">
  ### 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:

  | Field            | Meaning                                                                    |
  | ---------------- | -------------------------------------------------------------------------- |
  | `connected`      | Whether a connection is effective for this project.                        |
  | `shopDomain`     | The `*.myshopify.com` domain, or `null`.                                   |
  | `source`         | `project_override`, `account_default`, or `null`.                          |
  | `scopes`         | Granted OAuth scopes (space-separated), for "can the AI write?" reasoning. |
  | `toolsAvailable` | Whether the agent may call `shopify_*` tools for this project.             |

  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

  <Tabs>
    <Tab title="Read">
      | Tool                                | Proxies                              |
      | ----------------------------------- | ------------------------------------ |
      | `shopify_status`                    | `GET .../status[?include=catalog]`   |
      | `shopify_admin_ping`                | `POST .../admin/ping`                |
      | `shopify_admin_get_shop`            | `POST .../admin/get_shop`            |
      | `shopify_admin_list_products`       | `POST .../admin/list_products`       |
      | `shopify_admin_list_installed_apps` | `POST .../admin/list_installed_apps` |
      | `shopify_admin_app_compat_check`    | `POST .../admin/app_compat_check`    |
    </Tab>

    <Tab title="Write (admin/owner)">
      | Tool                                 | Proxies                               |
      | ------------------------------------ | ------------------------------------- |
      | `shopify_admin_create_product_draft` | `POST .../admin/create_product_draft` |
      | `shopify_admin_invalidate_cache`     | `POST .../admin/invalidate_cache`     |
    </Tab>

    <Tab title="Scaffold (any member)">
      | Tool                                    | Proxies                                  |
      | --------------------------------------- | ---------------------------------------- |
      | `shopify_scaffold_storefront_client`    | `POST .../scaffold/storefront-client`    |
      | `shopify_scaffold_revalidate_route`     | `POST .../scaffold/revalidate-route`     |
      | `shopify_scaffold_cart`                 | `POST .../scaffold/cart`                 |
      | `shopify_scaffold_sitemap`              | `POST .../scaffold/sitemap`              |
      | `shopify_scaffold_customer_account`     | `POST .../scaffold/customer-account`     |
      | `shopify_scaffold_product_detail_route` | `POST .../scaffold/product-detail-route` |
      | `shopify_scaffold_reviews`              | `POST .../scaffold/reviews`              |
      | `shopify_scaffold_subscriptions`        | `POST .../scaffold/subscriptions`        |
      | `shopify_scaffold_compat_check`         | `GET .../scaffold/compat?feature=<name>` |
      | `shopify_eject_manifest`                | `GET .../eject`                          |
    </Tab>

    <Tab title="Extensions">
      | Tool                         | Proxies                                        |
      | ---------------------------- | ---------------------------------------------- |
      | `shopify_scaffold_extension` | `POST .../scaffold/extensions/[feature]`       |
      | `shopify_deploy_extension`   | `POST .../deploy/extensions`                   |
      | `shopify_extension_status`   | `GET .../deploy/extensions/[sessionId]/status` |
    </Tab>
  </Tabs>

  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.
</Accordion>

## What's next

<CardGroup cols={2}>
  <Card title="Connecting Shopify" icon="plug" href="/integrations/shopify/connecting">
    OAuth flow, account-default vs project-override, what credentials get stored.
  </Card>

  <Card title="Storefront Scaffolding" icon="hammer" href="/integrations/shopify/storefront">
    What the AI agent generates: PDP, cart, JSON-LD, sitemap.
  </Card>

  <Card title="Adding to an existing project" icon="arrow-up-from-square" href="/integrations/shopify/retrofitting">
    Pre-flight compat check + dry-run for retrofits.
  </Card>

  <Card title="Shopify Overview" icon="store" href="/integrations/shopify/overview">
    The headless architecture and the Shopify-owns / Hiveku-owns split.
  </Card>
</CardGroup>