Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cartally.co/llms.txt

Use this file to discover all available pages before exploring further.

Regardless of the integration method (CMS or API), Cartally normalizes all product data into a consistent internal format. Understanding this format helps you optimize your product data for better search results.

​
Core product fields

Every product indexed by Cartally has these fields:
FieldTypeRequiredDescription
idstringYesUnique identifier. For variants: {product_id}-{color_slug}
product_idstringYesParent product ID (shared by all color variants)
variant_idstringYesVariant-level ID
product_namestringYesProduct title
product_descriptionstringYesPlain-text description (HTML tags stripped)
product_referencestringNoSKU or reference code
product_categoriesstring[]YesList of category names
photosstring[]YesList of image URLs
urlstringNoDirect link to the product page
price_{currency}integerYesPrice in minor units (e.g. cents). One field per currency

​
Dynamic attribute fields

Products may also have dynamic filterable attributes. These are stored as attribute_{slug} fields:
Example fieldTypeDescription
attribute_colorstring[]Color values (e.g. ["black", "red"])
attribute_sizestring[]Size values (e.g. ["M", "L", "XL"])
attribute_materialstring[]Material values
These attributes appear as filter facets in the search widget.

​
Color variants

Products with color variants are split into separate documents — one per color. This allows the widget to display the correct product image for each color. For example, a T-shirt available in black and red becomes two indexed documents:
  • 12345-black with photos of the black variant
  • 12345-red with photos of the red variant
Both share the same product_id (12345) so the widget groups them correctly.

​
Multi-language indexing

For multilingual stores, Cartally creates a separate search index per language. Product names, descriptions, and categories are stored in the respective language.

​
Multi-currency pricing

Prices are stored in minor units (cents/grosze) with one field per currency: 
{
  "price_pln": 9900,
  "price_eur": 2199,
  "price_usd": 2399
}
The widget automatically displays the price in the customer’s active currency. Cartally generates AI embeddings for each product using the product name and description. This powers semantic search — customers can describe what they need in natural language and find relevant products even without exact keyword matches.