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.

Shopify integration

The Shopify integration is the smoothest way to get Zubby AI running. The Zubby AI app authenticates via OAuth, reads your catalog and orders through the Admin GraphQL API, and adds the chat widget through a theme app embed that you switch on in one click - there’s no code to paste anywhere. Your Zubby dashboard runs at app.zubbyai.com; opening the app from Shopify admin takes you there.

Install the app

Start the Zubby AI installation from Shopify. You land on Shopify’s standard app approval screen.

1. 1

   Authenticate to Shopify

   Approve the connection with a user that has Apps and channels permission on the store you want to install on. A staff account needs the relevant app installation permission; ask the store owner if Shopify does not allow approval.
2. 2

   Approve OAuth scopes

   Review the 13 catalog, order, customer, content, policy, shipping, inventory, discount, fulfillment, product write-back and order-edit scopes shown by Shopify. The full breakdown is in the table below.
3. 3

   Land back in Zubby

   The store is connected as soon as you approve. If you installed from the App Store, create your Zubby account (or sign in) next - the store is attached to it automatically. The first catalog sync starts on its own, and the setup step links straight to the theme editor to turn on the chat widget.

Scopes explained

Each scope maps to one capability. If your security team needs to audit, here’s the breakdown:

First catalog sync

Shopify runs the initial pull as a bulk operation, so large catalogs import without paging through the API one product at a time. Small catalogs usually finish quickly; larger ones take longer. Progress shows in the onboarding wizard, and the synced products appear under Dashboard → Catalog (where you can also trigger a re-sync at any time).

After the bulk import finishes, Zubby prepares products for meaning-based retrieval. Search readiness can continue updating after the initial import reports completion.

Webhooks

Zubby subscribes to the following Shopify webhooks (API version 2026-10) through its app configuration, so they apply as soon as the app is installed. You don’t need to do anything - we verify the HMAC signature on every inbound event.

• products/create, products/update, products/delete
• collections/create, collections/update, collections/delete
• orders/create, orders/updated, orders/paid, orders/cancelled, orders/fulfilled, orders/partially_fulfilled
• refunds/create, fulfillments/create, fulfillments/update
• customers/create, customers/update, customers/delete
• carts/create, carts/update, checkouts/create, checkouts/update, checkouts/delete
• inventory_levels/update, inventory_items/update
• discounts/create, discounts/update, discounts/delete
• shop/update, app/uninstalled, app_subscriptions/update

The mandatory GDPR topics (customers/data_request, customers/redact, shop/redact) are handled separately at the dedicated privacy-compliance endpoint.

Embed the widget

Zubby uses Shopify’s Theme App Extension. Nothing is added to your storefront until you switch its app embed on and save the theme - Shopify does not let apps turn it on for you. The Zubby setup step has an Open theme editor button that opens the App embeds panel with the Zubby Chat Widget already selected; or do it by hand:

1. 1

   Open the theme editor

   Online Store → Themes → Customize on your live theme.
2. 2

   Toggle the App embed

   Click App embeds in the left rail. Find Zubby Chat Widget and switch it on. The store ID and widget key are pre-filled from app-owned metafields written at install - no copy/paste.
3. 3

   Save the theme

   Save and reload your storefront. Verify the launcher on an eligible page; loading depends on the theme, network and saved visibility rules.

Full walkthrough including block settings and the manual snippet at Embed the widget on Shopify.

Manual snippet (advanced)

If you want to embed without the theme app block - for example to gate the widget on a custom Liquid condition - paste the per-store loader just before </body> in your theme’s theme.liquid. Your store ID is shown in the Zubby dashboard; the loader bakes in the widget key and your saved widget design, so one tag is all you need:

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

Uninstalling

Uninstall from the Shopify Apps page. Zubby receives the app/uninstalled webhook, cancels any active app subscription, marks the store disconnected, and immediately revokes the access token and widget keys. Shopify then sends the shop/redact GDPR webhook (typically ~48 hours later), which queues the redaction of shopper data. You can re-install later - reconnecting the same shop re-activates the existing workspace.