Store connection, Shopify install, and Web Pixel

Simple terms

Store connection gets Apex onto the storefront and connects Shopify so events, products, orders, and revenue can flow.

Connects Apex to a storefront so experiments, analytics, Shopify events, product data, and revenue analysis can work.

Routes

• /installation
• /api/shopify/auth
• /api/shopify/auth/callback
• /api/shopify/*

Implementation behavior

• Shopify OAuth grants app scopes and stores installation metadata for the active shop.
• Theme app embed or manual snippet loads Apex Runtime on storefront pages.
• Shopify Web Pixel and event settings send checkout/order-related events that are not available from DOM-only tracking.
• Product, inventory, and order sync endpoints populate cost and reconciliation data when scopes are available.
• Install verification checks Apex Runtime reachability, snippet size, runtime settings, and recent events.

How to use it

• Use Shopify OAuth when the store is Shopify; use manual snippet for custom storefronts.
• Enable app embed or install the Apex Runtime snippet exactly once.
• Verify realtime events after installation.
• Reconnect Shopify when scopes, store permissions, or app access change.

When not to use it

• Do not install both manual snippet and app embed in a way that loads the SDK twice.
• Do not rely on Shopify revenue reporting without Web Pixel/event settings enabled.
• Do not debug experiments before install verification and realtime events pass.

Implementation source

• Install pages live under src/app/(dashboard)/installation.
• Handlers include /api/shopify/auth, /api/shopify/auth/callback, /api/shopify/settings, /api/shopify/snippet, /api/shopify/webhooks, /api/onboarding/verify-install, and /api/shops/runtime-settings.
• Runtime delivery uses the SDK package, Worker URL, Shopify installation metadata, and Web Pixel configuration.

Data and API

• Models include Shop, Shopify installation/session records, ShopifyEventSetting, product/order/cost sync records.
• APIs under /api/shopify/auth, /api/shopify/auth/callback, /api/shopify/settings, /api/shopify/snippet, /api/shopify/webhooks, /api/onboarding/verify-install, and /api/shops/runtime-settings.
• Runtime uses /api/exp, CDN SDK, Worker URL, and Web Pixel events.

Failure modes

• No storefront events: app embed disabled, snippet missing, blocked script, wrong shop ID, or Worker URL problem.
• OAuth failed: domain mismatch, missing scopes, or stale callback state.
• Revenue missing: Web Pixel or Shopify event settings are not enabled.