> ## 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.

# Product Data Model

> Understand how Cartally indexes and structures product data.

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:

| Field                 | Type      | Required | Description                                                  |
| --------------------- | --------- | -------- | ------------------------------------------------------------ |
| `id`                  | string    | Yes      | Unique identifier. For variants: `{product_id}-{color_slug}` |
| `product_id`          | string    | Yes      | Parent product ID (shared by all color variants)             |
| `variant_id`          | string    | Yes      | Variant-level ID                                             |
| `product_name`        | string    | Yes      | Product title                                                |
| `product_description` | string    | Yes      | Plain-text description (HTML tags stripped)                  |
| `product_reference`   | string    | No       | SKU or reference code                                        |
| `product_categories`  | string\[] | Yes      | List of category names                                       |
| `photos`              | string\[] | Yes      | List of image URLs                                           |
| `url`                 | string    | No       | Direct link to the product page                              |
| `price_{currency}`    | integer   | Yes      | Price 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 field        | Type      | Description                            |
| -------------------- | --------- | -------------------------------------- |
| `attribute_color`    | string\[] | Color values (e.g. `["black", "red"]`) |
| `attribute_size`     | string\[] | Size values (e.g. `["M", "L", "XL"]`)  |
| `attribute_material` | string\[] | 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:

```json theme={null}
{
  "price_pln": 9900,
  "price_eur": 2199,
  "price_usd": 2399
}
```

The widget automatically displays the price in the customer's active currency.

## Semantic search

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.