Existing Shopify connections: this reference supports stores already connected. New Shopify connections are coming soon. For new onboarding, use WooCommerce setup or Custom API on Pro or above.

Add an AI chat widget to your Shopify theme

For Online Store themes, use the App Embed no-code toggle. The manual snippet is reserved for headless or hyper-customized setups.

Option 1 - App Embed (recommended)

The App Embed is a theme app extension. Shopify supports app embed blocks in vintage and Online Store 2.0 themes; app blocks have different placement requirements. This is platform support, not evidence that Zubby has been tested on every theme. Existing authorized connections should verify their theme before publishing. For headless storefronts or a confirmed embed incompatibility, review the manual snippet below. Do not run the manual loader and app embed together. See Shopify app embed documentation.

1. 1

   Open the theme editor

   From your Shopify admin go to Online Store → Themes → Customize on the active theme.
2. 2

   Open the App embeds panel

   Click the puzzle-piece App embeds icon in the left rail. Shopify lists every installed app extension here.
3. 3

   Toggle Zubby Chat Widget

   Find Zubby Chat Widget and switch the toggle to on. The store ID and widget key fields pre-fill from app-owned metafields written at install, so you don’t need to paste anything.
4. 4

   Adjust settings (optional)

   The block exposes: widget color, position (bottom-right / bottom-left), welcome message, launcher label, a theme preset, and a display mode (floating bubble or inline block with a CSS selector). Deeper styling lives in the dashboard’s Widget Designer.
5. 5

   Save the theme

   Click Save in the top-right. Changes are live the moment you save.

Option 2 - Manual snippet

For headless storefronts (Hydrogen, Next.js Storefront API) or for full control on any theme, paste the per-store loader just before </body>. One tag - the widget key and design are baked into the script server-side.

<script
  src="https://app.zubbyai.com/widget/loader/YOUR_STORE_ID.js"
  defer
></script>

Your store ID is visible in the dashboard (Widget Designer’s embed panel also generates copy-paste snippets per display mode). The widget key is rotatable if leaked.

Logged-in customer identity on Online Store themes

On a supported Shopify Online Store account flow, the loader calls the App Proxy at /apps/zubby from the storefront; Shopify signs the request with logged_in_customer_id, and Zubby verifies that signature server-side and mints a short-lived identity token. The result: the AI greets signed-in customers by name and can answer order questions without asking for an order number - and a shopper can’t spoof someone else’s identity, because unsigned claims never unlock account data.

Verify the launcher

Open your storefront in a new tab. The launcher should appear in the saved position after the loader runs. If it does not appear:

• Open DevTools → Network. Confirm /widget/loader/<storeId>.js returns 200. A 404 means the store ID is wrong or the store is disconnected.
• Check for 401s on /api/v1/widget/* calls - that means the widget key was rotated or revoked; re-save the App Embed or re-copy the snippet.
• If you use the App Embed, confirm the toggle saved (Shopify’s theme editor occasionally swallows un-saved changes).
• See the full debugging playbook at Widget not loading.

Removing the widget

To hide the widget temporarily without uninstalling Zubby, toggle the App Embed off in the theme editor (or remove the manual snippet). Conversations and analytics keep working in the dashboard; only the storefront launcher is hidden.

Headless identity needs a separate check

A loader on a headless domain does not create a signed-in Shopify App Proxy session. Test as a guest and as a signed-in shopper; private order details must remain unavailable without verified identity. Review the custom integration and signed identity guide with your developer before promising account-aware support on a headless storefront.