Product Index

The product index is the searchable catalog IntentFlow uses for autocomplete suggestions and product cards.

Product fields

Field	Required	Description	Example
external_id	Yes	Merchant product identifier, unique within one store.	sku-1001
title	Yes	Product title shown in admin and search results.	Road Running Shoe
category	No	Category label used for category autocomplete results and AI phrase generation. Omit it (or leave it blank) when a product has no category.	Running Shoes
price	Yes	Product price as a non-negative decimal.	99.99
url	Yes	Public product page URL.	https://shop.example.com/products/road-running-shoe
image_url	No	Public product image URL.	https://cdn.example.com/products/1001.jpg
in_stock	No	Stock flag. Defaults to true when omitted.	true
additional_attributes	No	Extra product facts sent to AI phrase generation and indexed as searchable text. In CSV, use extra columns such as color or an attributes label/value column; in API imports, send an attributes object or extra product keys.	{"color":"blue"}

Optional enrichment-ready fields include description, brand, author, isbn, gtin, ean, sku, mpn, compare_at_price, currency, stock_quantity, and images. IntentFlow keeps the original payload in a raw snapshot and stores normalized fields separately for enrichment, exact matching, hybrid search, and smart collection assignment.

CSV import

The CSV file must include a header row. Header names are case-insensitive.

external_id,title,category,price,url,image_url,in_stock,color
sku-1001,Road Running Shoe,Running Shoes,99.99,https://shop.example.com/products/road-running-shoe,https://cdn.example.com/products/1001.jpg,true,blue

Any CSV column that is not a standard product field is stored as an additional attribute. For example, color,material becomes {"color":"blue","material":"mesh"}. An attributes column can also carry label/value pairs such as size: 42; color=blue, which becomes {"color":"blue","size":"42"}.

Import behavior

Behavior	Description
Upsert by product ID	Re-importing the same external_id updates the existing product.
Store scoping	The same external_id can exist in multiple stores.
Row validation	Invalid rows are skipped and reported without stopping the whole import.
Resume support	Background imports can resume from the last processed row.
Batched writes	Valid products and failed rows are written in fixed-size batches for large catalogs.
Downstream indexing	Only new or changed source hashes are queued for enrichment; enrichment saves suggestions, domain/profile metadata, search documents, and smart collection assignments.
Attribute changes	Category, exact fields, identifiers, stock, and additional attribute changes count as product changes, so they trigger fresh suggestions and indexing.

Ranking inputs

Autocomplete currently uses these ranking signals:

1. In-stock products before out-of-stock products.
2. Exact title match.
3. Title prefix match.
4. Generated intent phrase match.
5. Alphabetical fallback.

External search indexes also include title, normalized title, author, ISBN, SKU, brand, category, generated suggestions, enrichment profile search phrases, and additional attribute text. Search documents preserve the normalized base fields, the full attribute map, and generated search phrases so enrichment and retrieval can use all product facts the merchant provided.

PLACEHOLDER: Add final ranking controls for popularity, conversion rate, margin, merchandising boosts, and manual synonyms.

Index freshness

CSV uploads return immediately after the file is stored. Product rows become available after the background import worker processes the file. AI-generated phrases may appear later because enrichment runs on a separate rate-limited queue.

Operational limits

Limit	Value
Maximum CSV file size	50 MB
Recommended CSV batch size	10k to 20k products per upload
Maximum products per store	PLACEHOLDER
Maximum failed rows retained	PLACEHOLDER
Import retention period	PLACEHOLDER