Skip to main content

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.

Connecting Shopify is a one-time per-store action. After OAuth, every project on the same account inherits the connection unless overridden, and deploys automatically receive the right env vars.

​
Prerequisites

1

A Shopify store

A live or development Shopify store. Hiveku works with any plan (Basic and up). For native subscriptions you’ll also need Shopify Payments turned on — see Subscriptions.
2

Owner or admin role on the Hiveku account

Connecting a store writes account-scoped credentials. Member-role users can’t initiate the OAuth flow.
3

A Shopify OAuth app configured in Hiveku settings

One-time setup per Hiveku account: register a Shopify app in your Shopify Partner dashboard, then add its client_id + client_secret under Settings → OAuth apps in Hiveku. Subsequent stores reuse the same app.

​
The OAuth flow

1

Open the Shopify settings page

Navigate to /dashboard/commerce/settings/shopify.
2

Click "Connect a store"

A modal asks for two inputs:
  • Shop domain — the permanent *.myshopify.com domain (not your custom domain). Example: acme.myshopify.com.
  • OAuth app — picked from the apps you registered in Hiveku settings. If you only have one, it’s preselected.
3

Authorize on Shopify

Hiveku opens a popup pointing at https://{shop}.myshopify.com/admin/oauth/authorize. The merchant approves the requested scopes (read_products, write_products, read_orders, read_customers, etc.).
4

Hiveku finishes the handshake

The popup closes automatically. Behind the scenes:
  • Hiveku exchanges the OAuth code for an Admin API access token.
  • A Storefront API token is minted via Admin GraphQL storefrontAccessTokenCreate.
  • Both tokens are encrypted at rest with SHOPIFY_TOKEN_ENCRYPTION_KEY (AES-256-GCM envelope).
  • Webhook subscriptions are registered for the topics Hiveku needs (orders, products, subscription events, GDPR compliance).
  • The connection appears as Active in the settings UI.
The shop domain you enter must match what Shopify’s OAuth callback returns. The builder verifies the ?shop= query param against the domain you submitted to defend against shop-substitution attacks.

​
Account-default vs project-override

Hiveku’s Shopify connections follow a two-level model that’s optimized for agency users.

​
Account default (the common case)

The first store you connect on an account becomes the account default. Every project under that account automatically uses this connection — no per-project setup needed. 
Account: Locus Digital
└── Account default: locus-digital.myshopify.com
    ├── Project: Locus DTC website         ← inherits
    ├── Project: Locus client landing page ← inherits
    └── Project: Locus blog                ← inherits
This is the right setup when one Hiveku account = one brand = one Shopify store.

​
Project override (multi-shop agencies)

When a Hiveku account manages multiple brands, you can override the connection at the project level: 
Account: Locus Digital (agency)
└── Account default: locus-digital.myshopify.com (the agency's own shop)
    ├── Project: Roastline Coffee site → override → roastline.myshopify.com
    ├── Project: Beachwear Co site     → override → beachwear-co.myshopify.com
    └── Project: Locus internal blog   → inherit (uses account default)
To override on a specific project:
1

Open the project's settings page

/dashboard/[projectId]/settings
2

Find the Shopify panel

Toggle Override Shopify connection.
3

Pick a connection

Choose any active connection on this account. The project’s deploys will pull credentials from the chosen connection going forward.
You can also set a project to Disabled — useful when one project in a multi-shop account shouldn’t have any Shopify connection (a marketing site, for example).

​
What gets stored

Hiveku stores the bare minimum to operate the integration:
FieldStorage
Admin API access tokenEncrypted at rest (SHOPIFY_TOKEN_ENCRYPTION_KEY)
Storefront API tokenEncrypted at rest
Webhook secretEncrypted at rest
Shop domain, shop id, shop namePlain (used for routing webhooks + UI display)
Granted OAuth scopesPlain (compared against required scopes to detect drift)
installed_at, disconnected_at, last_synced_atPlain (lifecycle tracking)
Tokens never appear in the API responses to your browser or in logs. The connection list endpoint (/api/builder/shopify/connections) deliberately omits encrypted columns even from its select.

​
Multiple stores on one account

You can connect any number of Shopify stores. Only one can be the account default at a time; the rest are flagged purpose: 'project_override' and selectable as overrides. To swap defaults: disconnect the current default, then reconnect the store you want as the new default. Or connect both, then update purpose via admin tooling.

​
Disconnecting

1

Disconnect from Hiveku

Click Disconnect on the connection in /dashboard/commerce/settings/shopify. Hiveku marks the row disconnected_at = now(), stops registering webhook events, and clears the credentials from the next deploy. The Admin token is not force-revoked at Shopify — your Shopify admin can also un-install the app to be thorough.
2

(Optional) Uninstall in Shopify admin

Visit Shopify admin → Apps → uninstall Hiveku. Shopify revokes the token + fires app/uninstalled to Hiveku, which sets disconnected_at if it wasn’t already set.
After disconnect, your deployed sites lose access to Shopify env vars on the next deploy. The currently-running site keeps working until then. Plan accordingly if you need a clean cutover.

​
Reconnecting

If a store was previously connected, disconnecting and re-running OAuth updates the same row (matched by shop_domain) — webhook subscriptions, encrypted tokens, and timestamps all refresh in place. Project-level overrides survive.

​
What’s next

Build the storefront

What the AI agent scaffolds after a connection is active.

Adding to an existing Next.js project

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