Catalog & product sync

Your catalog is the foundation everything else stands on. Zubby AI can only recommend, search, and answer questions about products it has synced and indexed. This page explains where the catalog comes from, how it stays current, and how to read the data Zubby keeps about each product.

You’ll find it in the dashboard at Catalog → Products (the sidebar label is Products).

Where products come from

Shopify and WooCommerce products arrive through their connector. Custom or headless stores push products through the public API. A CSV import also exists for bulk-editing products already present in Zubby; it is not the initial custom-store ingest path.

Re-syncing on demand

For Shopify and WooCommerce, the Trigger sync button at the top of the Products page queues a full catalog sync - useful right after a bulk edit in Shopify or WooCommerce, or if you suspect something drifted. You can also rerun a connector sync from Catalog → Imports. Custom stores have no pull sync: re-send changed products through the catalog endpoint and use a periodic full re-push as a backstop.

How search and embeddings work

Syncing a product does two things. First, it stores the structured data - title, description, vendor, type, variants, prices, inventory, collections. Second, it generates a 1536-dimension embedding (a numeric fingerprint of the product’s meaning) and stores it with pgvector.

That embedding is what lets the agent do semantic search. When a shopper asks for “something warm for hiking in the rain,” Zubby combines semantic similarity with keyword matching for exact terms such as SKUs, then reranks eligible results. This is the same retrieval layer the knowledge base uses for policies and FAQs.

Content changes queue an embedding refresh. Search readiness depends on job completion and available AI service capacity; there is no fixed indexing-time guarantee. Inspect the Indexed badge and test the changed fact after the refresh.

Catalog overview metrics

The top of the Products page shows four counters so you can gauge whether the catalog is healthy enough to power good answers:

• Products - total synced products.
• Variants - purchasable variants across the catalog. Thin variant coverage makes recommendations feel shallow.
• Draft products - products still in draft state. Highlighted in amber because drafts usually shouldn’t be recommended.
• Descriptions missing - products with no description. These are the weakest links for AI answers and the best candidates for the AI Catalog Improver.

Below the counters, two demand cards - Back-in-stock demand and Price-drop demand - show how many shoppers are waiting on inventory or a price change, with the top products driving each. Use them to prioritize restocks and pricing reviews, or to spin up a journey.

The product list

Below the overview sits the product table. It is server-driven: search, filters, sorting, and pagination all re-query the full catalog, so you’re never limited to the rows already on screen.

• Search - the “Search all products” box matches across the whole catalog as you type.
• Filters - status chips (active / draft / archived), a product-type dropdown, and a collection filter when you arrive from the Categories page. Clear resets everything.
• Sortable columns - product, type, status, and updated date; 20 rows per page with Previous / Next paging.
• Per-row signals - price (or price range), stock (with “Out” and low-stock badges), status, and an AI column: an Indexed badge means the product has an embedding and is searchable by the agent; a sparkle marks AI-enriched attributes.
• Clickable rows - click anywhere on a row to open the product detail page.

Tick the checkboxes to select rows and a bulk action bar appears: Set status (active / draft / archived) and Re-index, which re-queues the selected products for embedding - handy after edits that didn’t seem to take. The Categories button in the header opens the Categories page, where you can browse collections and jump back to the list filtered to one of them.

Bulk editing with CSV import / export

The Import / Export button in the header is the fastest way to clean up a large catalog:

1. Click Export all products (.csv) to download the current catalog.
2. Edit the editable columns in a spreadsheet: description, seo_title, seo_description, product_type, status, tags (separated by |), training_notes, and boost_score. Leave the id column alone - rows match on it.
3. Re-upload the file with Import CSV. You’ll get a count of updated and skipped rows, with any errors listed.
4. Done - changed rows are re-indexed automatically. Supported fields can write back to Shopify or WooCommerce; custom-store edits remain local to Zubby until your source system re-pushes them.

Treat the commerce platform or custom source system as authoritative. For custom stores, push the same update from your source so a later full ingest does not overwrite a dashboard-only edit.

The product detail page

Click any product (or open one from a demand list) to see exactly what the AI is indexing for it. The detail page is laid out as:

• Product intelligence - status badge (active / draft / archived), vendor, type, and four metrics: variant count, recommendation events, back-in-stock subscribers, and price-drop subscribers. The stored description is shown verbatim, plus a plain- English read on whether inventory demand or price sensitivity is stronger right now.
• Collections - which collections or categories the product belongs to. Good categorization improves how the agent groups and cross-sells.
• Variants - SKU-level rows with title, SKU, price, compare-at price, and inventory quantity. This is where you verify that pricing and stock actually synced, not just the product shell.

The detail page also hosts the AI rewriting tools (Catalog Improver, PDP rewriter, and any nightly autopilot draft) and quick links to create back-in-stock or price-drop journeys for that product.

Product page Q&A

Included from the Growth plan up. Zubby writes three to five likely shopper questions with answers for your top-selling products, using only the product itself, your published policy documents, and the product’s review summary when there is one. The PDP Q&A card on the product detail page shows the block’s state (not generated, pending review, published, or rejected) and lets you regenerate, publish, or unpublish it.

New drafts wait in the moderation queue under AI Review until you approve them, unless you turn on auto-publish there. A published block keeps showing its approved answers while a refreshed draft waits for review. Blocks refresh when the product or its reviews change, or after 45 days.

On the storefront the block renders through the Shopify theme app block, the WooCommerce plugin, or an embed snippet on custom stores. It adds FAQ structured data to the page and an “Ask a follow-up” link that opens the chat.

Product costs and payment fees

The Cost coverage and Payment fees cards on Catalog hold the cost data behind profit reporting and the margin guard on AI discounts. See Profit & product costs for how to add costs on each platform.

What Catalog SEO health checks mean

Catalog SEO health checks active stored products for missing SEO title, missing SEO description, missing stored JSON-LD, and description length under 80 characters. It also flags nonempty titles under 30 or over 65 characters and nonempty descriptions under 120 or over 170 characters. These are internal editorial heuristics, not Google requirements, ranking scores, or a reason to pad accurate copy. Google can choose different title links and snippets.

Open an issue, inspect the affected product and fix its authoritative source where possible. Re-sync and recheck the stored fields. Separately inspect the actual public product page if your goal is search markup: a stored JSON-LD value does not prove your theme renders valid markup or qualifies for a rich result. Product Q&A markup does not promise Google FAQ rich results.

Worked example: verify a variant update

Illustrative staging catalog: a blue rain shell has sizes S and M, with M sold out. Correct its material in the source store, let the sync and indexing finish, then open its product detail in Zubby. Compare both variant prices, stock tracking and availability with the source. Ask the widget for the new material, the unavailable size, and an unrelated product. Expect the corrected fact and an appropriate alternative or clarification, not a fabricated available variant. Keep a draft product in the same test catalog and verify it is absent from recommendations.

Gotchas

• Drafts and archived products still sync so you can inspect them. The main product-retrieval paths filter to active products. Use exclusion rules for an active product you intentionally want omitted; investigate stale status or an unexpected result rather than treating a draft recommendation as expected behavior.
• No products after connecting? Confirm the Shopify authorization or WooCommerce plugin pairing finished, review Store Details and Notifications, then trigger one sync manually.
• Edited a product but the AI still cites the old copy? Check the source update, latest sync and Indexed state. Once refresh completes, ask the same question and inspect the returned product. Review indexing troubleshooting if it remains stale; repeated syncs alone do not diagnose the cause.

Related

• AI Catalog Improver - rewrite titles, descriptions, and SEO copy with brand voice.
• Product recommendations - how synced products get ranked and suggested.
• The AI agent - how retrieval turns your catalog into answers.
• Knowledge base - everything that isn’t a product (policies, FAQs, guides).