Schema and product sync

Why schema comes first

Schema tells To-AI how tenant taxonomy, collections, attributes, classifications, variants, and assistant-exposed fields should be interpreted. Product sync does not invent schema.

Schema lifecycle

1. POST /api/v1/catalog/schema-sync/runs with a stable idempotency key, source schema version/hash, and expected active version.
2. POST /runs/{run_id}/batches with ordered taxonomy, collection, attribute, and classification batches.
3. POST /runs/{run_id}/complete with the expected batch count.
4. Poll the run/current endpoints until activated.

Activation preserves retrieval policy. It must not silently disable semantic search or invalidate compatible embeddings.

Product delta lifecycle

Use POST /api/v1/catalog/index-sync/items/batch for normal deltas. Stable external_product_id is the identity. updated_at must increase monotonically. Unknown request fields fail closed so typos cannot look successful.

Send only changed products. If one description changes, only that product receives a new content hash/projection version and embedding refresh. Unchanged accepted items may return an unchanged/deduplicated status rather than creating work.

Product descriptive sync intentionally excludes inventory quantities. Product/variant/location quantities belong to signed inventory events.

Large catalogs

For initial or large syncs, use the run APIs and respect the discovered limits. Pace batches and retry 429/503 with exponential backoff and jitter. Keep the same logical idempotency key on a retry.

Readiness

Exact/lexical search can remain usable while semantic embeddings warm. Poll capabilities and require the lane/index state appropriate for your launch; do not assume policy enabled means embeddings are ready.