Core concepts

Sources

A source is a connection to where your product data lives — a WooCommerce, BigCommerce, or Magento store, an existing feed URL (Google Shopping XML or CSV), a CSV/XLSX upload, or an API push source created automatically when you use POST /api/v1/catalog. A workspace can have multiple sources, and each syncs independently.

The canonical model

Every connector normalizes into one canonical product shape: externalId, title, description, brand, url, imageUrl, priceMinor, currency, availability, gtin, mpn, and variants. Prices are integer minor units (e.g. 2450 for €24.50) with an ISO-4217 currency; availability is the ACP enum (in_stock, out_of_stock, pre_order, backorder, unknown). Audit, enrichment, and every feed renderer work from this one model.

Readiness score

The readiness score is a 0–100 number summarizing how agent-ready a catalog is. Each SKU starts at 100 and loses the weight of every rule it fails; the catalog score is the average across SKUs. Missing seller settings (name, URL, store country) cap the catalog score at 40 until fixed, because no feed item is valid without them.

• A (90–100): agent-ready.
• B (75–89): mostly ready with a few high-impact gaps.
• C (60–74): meaningful issues that suppress discoverability.
• D (40–59) / F (<40): critical failures across much of the catalog.

Rules & severity

A rule is a single check applied to every product — for example gtin_missing or description_thin. There are 12 weighted rules plus a catalog-level seller-settings check; see running an audit for the full table. Every finding carries a severity:

• Error: a spec violation or missing required field — the item is not eligible on the target surface until fixed (missing price, non-HTTPS URL, invalid GTIN).
• Warning: hurts discoverability significantly (missing GTIN, missing brand, unknown availability).
• Info: quality improvements that raise match rates over time (thin descriptions).

Enrichment

Enrichment is Claude-assisted content generation for products with content gaps. ShelfReady drafts titles, descriptions, and brands from your existing data, each with a rationale. Nothing is applied without explicit approval.

Feeds

A feed is a rendered, hosted representation of your catalog in a specific format — OpenAI ACP (CSV and JSON), Google Merchant Center TSV, or schema.org JSON-LD. Feeds live at stable tokenized URLs of the form /f/<slug>/<token>/<file> and re-render automatically after every sync.

Freshness

Pull sources re-sync every six hours, and each sync cascades into a feed re-render and a fresh audit. A daily drift check fetches your live product pages and compares price and availability against the catalog, emailing you a digest when something drifted. Continue to connecting a store to put these concepts into practice.