Skip to main content

Shopify

Audience: Sales, management, support, engineering · Where in app: Settings → Integrations → Shopify · Plan availability: Pro (verify)

Shopify makes the AI product-aware. It syncs the store's product catalog into Knock Knock's RAG (retrieval) store, embeds each product for semantic search, and lets the chat/voice agent search and recommend products in the middle of a conversation ("running shoes under $100"). Webhooks keep the catalog fresh as products change.

What it does​

  • One-time + ongoing sync of products → rag_products (ms-ai), per company.
  • Embeds each product for semantic (vector) search.
  • Lets the AI agent search and recommend products via the fetch_products_catalog tool.
  • Tracks what a visitor looked at as a lead-score signal (product_searched).

How it works​

Auth model: OAuth. Connect from Settings → Integrations → Shopify. Uses the Shopify GraphQL Admin API (@shopify/shopify-api, API version April23) with the read_products scope. OAuth tokens are cached in Redis and proactively refreshed (~2 hours before expiry). Connection/credentials live on the ms-ai integrations row (platform: "shopify", credentials.shop).

Direction: inbound (read-only product sync). Knock Knock reads the catalog; it never writes to Shopify.

What gets synced (per product → rag_products)​

id, name, product_type, status, vendor, description, thumbnail, permalink, variants[] (sku, price, inventory, compareAtPrice), stock_status, on_sale, categories, tags, brands, attributes, and date_modified_gmt (used for change detection). Computed pricing fields: product_price, product_price_max, price_type (ZERO / NUMERIC / RANGE).

Each product is embedded with text-embedding-3-small (1536-dimension vector, configurable via EMBEDDINGS_MODEL) and stored in the rag_products table with the vector column.

Webhooks​

Shopify webhooks are registered for:

TopicEndpointEffect
PRODUCTS_CREATE/integrations/shopify/products-create/{integrationId}New product embedded
PRODUCTS_UPDATE/integrations/shopify/products-update/{integrationId}Product re-embedded
PRODUCTS_DELETE/integrations/shopify/products-delete/{integrationId}Product removed from RAG

Webhook calls are verified via the x-shopify-hmac-sha256 header (HMAC-SHA256, base64, timing-safe comparison). Re-embedding only happens for products whose date_modified_gmt is newer (batch upsert change detection).

AI agent usage​

The agent's fetch_products_catalog tool takes product_name, price_min, price_max; the search runs a vector ANN query over rag_products (scoped by company/integration, filtered by price) ordered by vector distance, limited to ~10 results, then the agent summarizes and recommends. A successful lookup emits the product_search event and bumps lead_score.product_searched.

Configuration & options​

ActionRoute
Create integrationPOST /integrations/shopify
Integration statusGET /integrations/:id (returns shop, scopes, missing_scopes, webhooks, webhooks_ok, missing_webhooks)
Remove (cleans up webhooks)DELETE /integrations/:id

Sync status (integrations.sync_status): pending → in_progress → completed, with retry / failed on error. Status, scopes, and webhook health are surfaced on the integration detail screen.

Behaviors & edge cases​

  • Products not showing up: check sync_status; if failed, see the error and force a re-sync from the admin UI.
  • Out-of-stock recommendations: the sync embeds catalog metadata, not live inventory levels — inventory-aware recommendations are roadmapped, so the AI can occasionally surface out-of-stock items.
  • Variant explosion: a product with 50 variants is one embedded item — variant-specific recommendations are limited.
  • Currency: uses Shopify's display currency; multi-currency stores may need explicit handling.
  • Large catalogs: initial sync takes time (surfaced via sync_status: in_progress → completed).
  • Disconnect: removing the integration deletes its products and de-registers the Shopify webhooks.

Plan & limits​

  • Marked Pro in the knowledge base (verify exact tier gating).
  • Product count per company depends on plan; re-embedding consumes AI credits.

Technical implementation​

  • Owning service: ms-ai — src/integrations/rag/shopify/shopify.service.ts, shopify.controller.ts, shopify-token.service.ts. Shared product store/search in src/integrations/rag/rag-product/ and the products.tool.ts agent tool.
  • Integration entity: src/integrations/entities/integration.entity.ts (platform, credentials jsonb, sync_status, type: rag).
  • Embedding model: text-embedding-3-small. Env: AI_BASE_URL (webhook callbacks), EMBEDDINGS_MODEL (optional override).
  • See Knowledge Base & RAG.

What Nox can tell you​

  • Connection status, product count, last sync time.
  • Top products by AI search count; visitors who searched products but didn't book.

Tools: standard session/aggregate tools filtered on products_searched.