Understanding enrichment

Plans: Starter (limited credits) · Growth · Pro · Agency

For step-by-step instructions on how to enrich (single, bulk, wizard) for products, categories/collections, and pages on both BigCommerce and Shopify, see Enrich your catalog. This page covers the conceptual model of what enrichment produces and the differences in inputs across platforms.

Every time Clione enriches an entity (on demand from any listing or detail page), it generates six categories of artifacts from a single LLM call + an embedding call.

The same model applies to all four entity types: products, BC categories, Shopify collections, and content pages. Where this page references "product" below, the same applies to the other types (the artifact set is identical — the only difference is which fields the LLM is shown).

#	Artifact	Used by
1	Semantic text — identity, reasoning, objection handler	LLMs, internal search
2	Quality scores — durability, quality, value-for-money, price positioning	Dashboard, ranking
3	Bilingual keywords (EN + ES)	Search, tag clouds
4	Vector embedding (1536-dim)	Semantic similarity search
5	JSON-LD (schema.org/Product)	Search engines, LLM crawlers
6	SEO meta signals — description, canonical URL, keywords	SEO tools, headless storefronts

What goes into the LLM call

Your product's title, description, price, vendor, categories — that's it. Plus any hints you added via the Enrichment Wizard (target audience, materials, competitor names, etc.) if you filled it.

The LLM doesn't have access to your reviews, returns, conversion rate, or sales data yet. That means:

• The identity and reasoning fields are sharp — the LLM is great at summarising product character from titles and descriptions.
• The quality scores are educated guesses — the LLM has common sense about markets (Hermès→luxury, Primark→budget) but it's reading your catalog text, not verified performance data.

See Understanding Quality Scores for the full breakdown and what we're building to fix this.

What's actually shown to the LLM per platform

The semantic prompt is the same on both platforms. What differs is the shape of the input record the synchronizer hands to the LLM, because each platform organizes the catalog differently.

BigCommerce

Field on the BC side	Field name in the prompt	Notes
name	title	Always sent.
description	description	HTML stripped to plain text before sending.
price + sale_price + cost_price	price, salePrice	Sent in the store's default currency.
brand_id → brand name lookup	vendor	Resolved via /v3/catalog/brands/:id.
Categories (array of IDs) → category name list	categories	Path is flattened, e.g. Home > Bedding > Sheets.
options[] (size, color, etc.)	options	Sent so the model can name variants in the reasoning.
meta_keywords, search_keywords	existingKeywords	The LLM uses these as seeds, not as truth.
Images (/products/:id/images)	imageCount	Only the count — the model is text-only.

Shopify

Field on the Shopify side	Field name in the prompt	Notes
title	title	Always sent.
bodyHtml	description	HTML stripped.
variants[0].price + compareAtPrice	price, salePrice	Default currency from the shop's primary Market.
vendor	vendor	Sent verbatim.
productType + collection memberships	categories	Manual + smart collections both count.
options[] and variant matrix	options	All combinations sent compactly.
tags (comma-separated)	existingKeywords	Used as seeds.
images.edges.length	imageCount	Only the count.

The model is shown which platform it's writing for so it can avoid awkward edge cases (e.g. it knows not to invent a gtin field if the platform didn't expose one).

What happens on re-enrich

• A new version of the enrichment is snapshotted (the previous output is retained in History)
• The last 3 versions per product are kept automatically — older ones are purged
• You can restore any past version from the product's History tab
• If the product was manually edited, the re-enrich dialog asks you to type OVERWRITE to confirm losing the manual edits

Cost and credits

Each enrichment call consumes one enrichment credit. Bulk enrich consumes one credit per entity in the batch.

Plan	Monthly credit allowance
Starter	250
Growth	2,500
Pro	25,000
Agency	100,000 (pooled across all stores on the tenant)

Credit usage is shown in Org → Plan with a per-store breakdown and a daily burn-rate sparkline. Re-enriching the same entity consumes another credit — there is no free reprocess.

If you run out mid-month, enrichments queue but don't dispatch; the dashboard shows a banner with the upgrade hint. Existing enriched content keeps serving — only new requests are paused.

Where enriched content is exposed

• Inside the dashboard — for you to review, edit, rollback
• Via API endpoints — .llm, .jsonld, .meta variants per product
• Via /.well-known/llms.txt at your tenant domain — a catalog manifest that LLM crawlers can fetch
• Via the embed script — injected FAQ widgets + JSON-LD on your storefront pages
• Via the Schema Injector — BC Scripts API on BigCommerce, Theme App Extension on Shopify (see Schema Injector)

Per-platform differences in what propagates

Once enriched, the propagation step pushes the result back to the storefront. Both platforms receive the same content, but the destination fields differ:

BigCommerce — propagation targets

• page_title (meta title) on /v3/catalog/products/:id
• meta_description on the same endpoint
• meta_keywords and search_keywords (BC-only field)
• clione_jsonld custom metafield in the clione namespace, set via /v3/catalog/products/:id/metafields
• For categories: same page_title / meta_description / meta_keywords on the category resource

Shopify — propagation targets

• metafields.global.title_tag (this maps to the SEO title in the storefront)
• metafields.global.description_tag (maps to the meta description)
• metafields.clione.jsonld (the rendered JSON-LD blob, served by the theme app extension)
• metafields.clione.faq (FAQ payload consumed by the FAQ widget)
• tags are not modified — Shopify uses tags for merchandising and Clione doesn't overwrite them

See Concepts → Signal Propagation for the full propagation matrix.

Troubleshooting

"Out of credits" toast after a bulk enrich — The batch was partially processed; the remaining entities are queued. Upgrade your plan or wait for the credit cycle reset (1st of the calendar month, UTC).

Re-enrich produces wildly different scores — The LLM has temperature > 0 by design (to avoid over-fitting). Lock in your reasoning by filling the Enrichment Wizard's evidence section — see Understanding scores.

Enriched but storefront still shows old meta tags — Propagation runs async, ~30 seconds after enrichment finishes. Hard-refresh the storefront page; if still stale after 5 minutes, check the Verification view for the propagation error.

BigCommerce metafield write fails with 422 — The metafield namespace must be clione. If you created a different namespace manually, delete it and let Clione recreate. The dashboard surfaces this as a propagation error.

Shopify enrichment runs but JSON-LD is missing from the live page — The theme app extension is not enabled. Open Theme Editor → App embeds → enable "Clione JSON-LD". See Schema Injector — Shopify.

Check the Concepts → Enrichment Pipeline for the full technical reference.

Per-entity-type artifact map

While the artifact categories are the same across products, categories/collections, and pages, the exact fields differ slightly:

Field	Product	Category (BC) / Collection (Shopify)	Page
core_identity	✓	✓	✓
recommended_for	✓	✓ (audience for the category)	—
decision_logic	✓	✓	—
objection_handler	✓	—	—
target_audience	✓	✓	✓
purchase_intent	✓	—	—
content_purpose	—	—	✓
seasonal_relevance	✓	✓	—
meta_title	✓	✓	✓
meta_description	✓	✓	✓
search_keywords (EN+ES)	✓	✓	✓
quality_perception	✓	—	—
value_for_money	✓	—	—
price_positioning	✓	—	—
typical_competitors	✓	—	—
content_freshness	—	—	✓
related_entities	✓	✓	✓
embedding (1536-dim)	✓	✓	✓
jsonld (Product)	✓	—	—

Categories and pages don't get a JSON-LD blob today — that's planned. They get meta + reasoning + keywords + embedding, which is what Clione's own internal search uses.

Sanity-checking enrichment before propagation

The auto-propagator runs ~30 seconds after enrichment finishes. If you want to inspect the result before it lands on your storefront, you can pause auto-propagation per store: Store → Settings → Auto-propagate toggle. With it off, enrichment runs but propagation is queued for manual approval — review the entity in the Propagation tab and click Push to storefront when ready.

Auto-propagation is on by default because the friction of approving every enrichment kills throughput. Turn it off only when you're QA'ing a sensitive catalog (e.g. fashion luxury, regulated categories).

Language and locale of enrichment

The LLM produces output in the same language as the input by default. If your product description is in English, the enriched copy is in English. If it's in Spanish, the copy is in Spanish.

For bilingual stores:

• Search keywords are always bilingual (EN + ES) regardless of input language.
• Meta title / meta description match input language. To get a Spanish meta on an English description, use the Enrichment Wizard → Locale override field.
• JSON-LD uses the same language as meta.

Multi-locale propagation (writing the Spanish meta to a Spanish-locale Shopify Market) is on the roadmap.

Enrichment chip lifecycle

While an enrichment is running, a persistent chip appears in the dashboard's top bar:

1. Queued — job accepted, waiting for a worker.
2. Running — LLM call in flight; progress shown as N / total for bulk.
3. Propagating — pushing to the storefront.
4. Done — auto-dismisses after 5 seconds.
5. Error — stays visible until you dismiss; click to see the error details.

The chip persists across page navigation so you can leave the page and come back. Closing the tab cancels the chip but doesn't cancel the background job — re-open the dashboard to find the result.

Side-effects of enrichment

Enriching a product does not:

• Change the upstream catalog's price or inventory.
• Trigger a sale notification or webhook to your customers.
• Affect search-engine ranking immediately (Google takes weeks to re-crawl).
• Modify your theme.

Enriching does:

• Write meta title and meta description back to the platform via Admin API.
• Write JSON-LD metafield (BC: clione namespace; Shopify: clione namespace).
• Trigger an automatic Verification check 30 seconds later.
• Consume one enrichment credit.
• Create a version snapshot.
• Update Clione's vector index for semantic search.

Per-store vs cross-store enrichment

Enrichment is per-store. The same SKU on a BC store and on a Shopify store gets enriched separately, and the resulting content may differ slightly because the inputs (description, vendor name, etc.) differ.

If you want consistent enrichment across stores with overlapping catalogs (common in agency setups), the workflow is:

1. Enrich on the primary store.
2. Export the enrichment from the product detail's Raw JSON tab.
3. Use the API to write the same enrichment into the secondary store. See developers/products-api.

Cross-store enrichment cloning is on the roadmap.