> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yourhomie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Product feed and field mapping

> Load a market's product feed and map its columns to the product fields, from availability and prices to energy labels and documents.

Every market reads its products from a **product feed**: a structured file such as a Google Shopping, XML, TSV, CSV, or JSON feed that the platform loads from its URL. The **field mapping** decides which column fills which product field.

## Load a product feed

**1. Add a market**

Open the catalog, go to **Markets** and select **Add market**. For the first market of a new catalog you land here directly.

**2. Load the product feed**

In the **The market's product feed** card, enter the URL of your product feed, for example your Google Shopping feed or a CSV, XML, or JSON file, and select **Load product feed**. Format, delimiter, and XML element are automatic by default. If needed, you can set them yourself right below, for example the **XML element per product** such as `channel.item`.

**3. Set up the market**

In the **Market** card you set:

* **Name** — how the market is named in lists, for example "Germany" or "Switzerland (French)".
* **Language of the product texts** — preselected: the detected language, otherwise German. Check it before you create the market: it is the market's base language and determines how product texts are searched.
* **Countries** — the countries the market serves.
* **Currency** — the currency of the prices in your product feed.

The **Product feed** card shows the URL and the number of rows; **View feed preview** opens a preview of its rows.

**4. Review the field mapping**

Assign the columns of your product feed to the product details and check the suggestions. The sections below explain the individual fields.

**5. Set the automatic import**

In the **Automatic import** card, choose under **Frequency** how often the market is imported: **Daily**, **Hourly**, or **Manual only**. With **Daily** you pick the **Time** in your time zone. **Hourly** is only available on a higher plan.

**6. Create the market**

Select **Create market**. The first import then starts automatically.

> [!NOTE]
>
> Three fields are required for every product: a unique **Product ID**, the **Product name**, and the **Product URL**. The **Image** is optional and sits under **Product details**: a product without an image shows a neutral placeholder. The **Price** is optional and sits under **Prices**: if your feed has no prices at all, for example a B2B catalog, leave it unassigned; the products then have no price.

You change the field mapping later in the market's **Field mapping** tab. Changed assignments start a new import when you save. You change the name, language, countries, and currency in the **Settings** tab, in the **General** card; a changed language or currency also starts a new import when you save. You change the automatic import there in the **Automatic import** card.

### Change the product feed

In the **Settings** tab, you can change the URL of the product feed in the **Product feed** card. When you save, the new file is loaded first and then imported. Saving is refused when the file cannot be loaded or another market already uses this URL. The columns of the new file must match the field mapping; the next import report shows missing columns. You set format, delimiter, and XML element in the same card.

## Review the suggestions

Wait for the feed to finish loading, then check the suggested columns. Choose a column yourself wherever a field is still empty.

Recommended fields carry the label **Recommended**: price, strikethrough price, availability, image, brand, GTIN, description, category, variant group, and variant options. Map them when your product feed contains them.

> [!NOTE]
>
> Only your saved mapping applies. If you add or rename columns in your feed later, update **Field mapping** as well.

The import report names rows the import rejects, for example because the product name is empty or a price cannot be read.

## Excluded fields

The assistant can still use columns you don't map to a field as additional product information. Under **Excluded fields**, select columns that should not be used for customer advice, such as internal notes. The card offers columns that are not already mapped to a field. Review this selection before your first import.

An excluded column cannot also be part of the **ID Search**, **Compatible with**, **Cross-reference numbers**, **Product documents**, **Advisor notes**, or **Consumer notices**: the platform does not offer it there, and you cannot exclude a column you picked there.

## Availability

Use availability to keep the assistant from recommending products customers cannot order.

**1. Choose the availability column**

In **Availability**, select the column that says whether each product can be ordered.

**2. Assign the values**

Under **Found values**, check every value from your feed. Assign each one to **Available**, **Not available**, **Preorder**, or **Backorder** before saving.

**3. Add stock if available**

Under **Stock**, select the column with the quantity in stock. If you also mapped availability, that status determines whether a product is available. Stock supplies the quantity only.

If you map only **Stock**, a whole number above zero counts as available; zero or less counts as unavailable. Empty or invalid quantities are rejected. If you map **Availability**, empty or unrecognized status values can cause rows to be rejected. Review the [import report](https://docs.yourhomie.ai/en/user-guide/knowledge/catalog/imports.md#review-imports) and correct the feed or mapping.

> [!WARNING]
>
> Without availability or stock information, all products count as available. Check the mapping before using the catalog for recommendations.

### Price hint and availability hint

You can optionally map a **Price hint** and an **Availability hint**. homie shows both texts exactly as your feed delivers them on the product tile: the price hint under the price, for example a base price such as "209,50 € pro 1 l" or a sales unit such as "pro Eimer", and the availability hint as the delivery line, for example "Lieferbar in ca. 46 Tagen". homie never generates these texts itself. A blank cell removes the text with the next import. The price hint belongs to the price from your feed: when the assistant names a price from a price list, it is not shown.

## Prices

Map your normal price column to **Price**. If your feed has a second price column, map it to **Strikethrough price**: in a Google feed that is `sale_price`, in a Shopify export `compare_at_price`; columns such as `uvp` or `list_price` belong there too. The platform suggests the mapping this way.

The two price columns are read together, row by row:

* **Both filled with different amounts:** the lower amount is the price, the higher one is shown struck through.
* **Both filled with the same amount:** that amount is the price, without a strikethrough price.
* **Only one of them filled:** that amount is the price, without a strikethrough price.

When a **Price** or **Strikethrough price** column is assigned and a row has no price in either column, or its price cannot be read, the product is still imported, without a price. The import report shows how many rows have no price, with an example.

A price is a single amount with an optional currency, for example `1299.00`, `1.299,00 €` or `EUR 1,299.00`. Texts such as `from 12.99` or a price range are not read as a price. A single dot or comma is read as the decimal separator: `1.299` is 1.30, not 1,299.

When no price column is assigned, every product is imported without a price: the product tile shows no price line, and the assistant never invents a price for them. How the assistant mentions products without a price is set in the assistant with **Products without a price** (see [General settings](https://docs.yourhomie.ai/en/user-guide/assistants/general-settings.md#options)). Products without a price are still found and can be recommended. When a visitor asks for a price range or for products on sale, only products with a valid price qualify; when results are sorted by price, products without a price appear last.

In the **Prices** card you also set:

* **Gross or net:** under **Prices are**, whether your feed's prices are **Gross (incl. VAT)** or **Net (excl. VAT)**. A new market starts with gross. With **Not specified**, the assistant states neither gross nor net for these prices and names no VAT rate; choose one as soon as you know it.
* **VAT rate:** optionally a column with the VAT rate per product, for example `19` or `7`. Without a VAT rate, the assistant only says "incl. VAT" or "excl. VAT" without a percentage.
* **Unit price:** map **Content** and **Reference quantity**, for example `750 ml` and `1 l`; these match the Google fields `unit_pricing_measure` and `unit_pricing_base_measure`, which the platform suggests for them. The assistant then names the unit price for whichever price it mentions, including prices from a price list. A ready-made unit price text as the price hint, by contrast, only applies to the price from your feed.
* **Shipping costs:** optionally a column with the shipping costs per product. It holds either an amount that applies to every country, for example `4.95`, or entries per country in Google's notation, for example `DE:::4.95 EUR,AT:::9.90 EUR`. The assistant names the shipping costs for the conversation's country; if there are none for it, it says that it does not know them.

You set the currency of your product feed's prices in the **Market** card under **Currency**. It is the market's currency; price lists only apply to markets with the same currency (see [Price lists](https://docs.yourhomie.ai/en/user-guide/knowledge/catalog/supplemental-data.md#price-lists)).

### Sale period

Optionally, map a **Sale period** to limit a reduction to a period, as Google's `sale_price_effective_date` does. The platform suggests that column for it. The period is written as `start/end` in ISO 8601, for example `2026-10-01/2026-10-31` or `2026-10-01T00:00+0200/2026-10-31T23:59+0200`:

* The time is optional; a date without a time covers the whole day (UTC).
* Either side can stay open, for example `/2026-10-31` for a sale that ends on October 31.

Within the period, the lower price applies and the higher one is shown struck through. Before and after it, the higher price applies without a strikethrough price. Without a sale period, or with one that cannot be read, the lower price always applies.

## Product details

Under **Product details**, next to brand, GTIN, and category, you map:

* **Image** — the column with the link to the product image. A product without an image shows a neutral placeholder.
* **SKU** — your own article number, when the feed has a column for it. A market can use it to recognize the same product in its other markets (see [Product key](https://docs.yourhomie.ai/en/user-guide/knowledge/catalog/markets.md#product-key)).
* **Manufacturer part number (MPN)** — the number the manufacturer gives the product, for example `19302061440`. Visitors can find the product by it. If you map no column here, a column with the Google name `mpn` is used.
* **Description** — the column with the long product text.
* **Condition** — whether a product is new, refurbished, or used. The platform understands the Google values `new`, `refurbished`, and `used` as well as the German terms `neu`, `generalüberholt`, and `gebraucht`. When a product is not new, the assistant always mentions its condition along with the product.
* **Energy efficiency class** — the class according to the EU energy label, for example `A` or `A+++`. The assistant names it in the conversation.
* **EPREL registration number** — the product's number in the EU product database EPREL, for example `123456`, or the link to it. The assistant uses it to link the energy label and the product information sheet. If the energy efficiency class is missing, it is taken from the EU register.

The platform suggests the energy fields when the columns carry the Google name `energy_efficiency_class` or common names such as `energieeffizienzklasse` or `eprel`.

### Advisor notes

Under **Advisor notes** you can optionally pick columns with internal notes that steer the assistant's advice, for example "Recommend to professionals only". They guide recommendations rather than serving as customer-facing product text. Select these columns yourself; they are not suggested automatically.

### Consumer notices

Under **Consumer notices** you can optionally pick columns with legal or safety notices, for example warnings for toys or chemicals. These are customer-facing texts. Keep them complete and check how they appear in a test conversation.

Every notice has a type: **Legal notice**, **Safety warning**, or **California Proposition 65 warning**. The platform only offers the California Proposition 65 type for markets that serve the US. You can use these formats:

* **Google format:** a cell such as `safety_warning:Not suitable for children under 3.` names its own type (`legal_disclaimer`, `safety_warning`, or `prop_65`). Separate several notices with commas. In XML feeds the platform reads Google's `consumer_notice` group with `notice_type` and `notice_message`.
* **Your own columns:** every other filled cell is a notice of the type you choose under **Type of notice when the cell names none**. The default is **Safety warning**.

Keep each notice within 1,000 characters so it is not cut off. A market's translations can translate the consumer notices as well (see [Translations](https://docs.yourhomie.ai/en/user-guide/knowledge/catalog/markets.md#translations)).

## Sorting in search

Use **Sorting in search** to prefer certain products among similarly relevant results. Map your numeric ranking column under **Ranking**, then choose **Higher value is better** or **Lower value is better** under **Ranking order**.

For a popularity rank where 1 means most popular, use **Popularity**. It gives popular products a smaller preference. Test a few typical customer questions after changing these settings.

## Variants

Under **Variants** you map the **Variant group**, the **Variant options**, and the **Shared title**:

* Rows with the same value in the **Variant group** (Google `item_group_id`) belong to one product. Rows without a variant group are products of their own.
* The **Variant options** say per row how a variant differs, for example `color:red,size:L` (Google attribute `variant_option`).
* The **Shared title** is the name all variants share, for example "Work jacket Pro" instead of "Work jacket Pro red L" (Google attribute `item_group_title`).

### Related products and successors

Under **Product relations** you link products to each other:

* **Related products** — choose a column containing the identifiers of related products. Separate multiple identifiers with commas, semicolons, or vertical bars. Each product keeps up to 1,000 per row; the import report names rows with more.
* **Default relationship** — after selecting the column, choose how those products relate: **Accessory**, **Required part**, **Part of a set**, **Often bought together**, **Alternative**, or **Same product from another brand**.
* **Successor** — choose the column identifying the product that replaces this one.

> [accordion] Using a Google related-product field
>
> A Google-format entry includes the relationship, identifier type, and identifier, for example `accessory:gtin:4006381333931,required_part:id:AZ7A`. It uses its own relationship instead of **Default relationship**. In XML feeds, use the `related_product` group with `relationship_type`, `identifier_type`, and `identifier`.

The platform looks up plain IDs and successors by the key you chose for the market: product ID, GTIN, or SKU (see [Product key](https://docs.yourhomie.ai/en/user-guide/knowledge/catalog/markets.md#product-key)). It finds entries in the Google format by the row's ID in the feed or by the GTIN. Only products of the same market are linked. The import report shows per field how many entries were matched to a product and how many were not, with examples of the values that were not found.

Test a question about a product with accessories or a successor in the Playground. Whether unavailable products appear depends on **Show unavailable products** in the [assistant's product settings](https://docs.yourhomie.ai/en/user-guide/knowledge/product-data.md#choose-a-catalog-for-an-assistant).

### Compatible with

Use **Compatible with** for spare parts, accessories, and consumables that fit devices, models, systems, or series that are **not** products in your shop, for example a battery that fits the drills `Makita 6211DWH` and `Makita 6311DWH`. Visitors can then ask for "a battery for my Makita 6211DWH" and find the product.

Under **Compatible with**, choose the columns that list these devices. Separate several entries in a cell with commas, semicolons, vertical bars, or line breaks. A column used here has no other role: it is not mapped to a field, not excluded, and not part of another list such as the **ID Search**.

Each product keeps up to 25,000 entries per field; the import report names rows with more.

### Cross-reference numbers

Use **Cross-reference numbers** for the original (OEM) or comparison part numbers a product replaces, for example `BL1830` or `194204-5` for a replacement battery. Visitors can then ask for "a replacement for BL1830". Choose the columns the same way as for **Compatible with**.

> [!NOTE]
>
> Both fields describe items that are not in your shop. To link products of your own shop, use **Related products**; for the product that replaces this one, use **Successor**. The product's own numbers belong under **GTIN**, **Manufacturer part number (MPN)**, or the [ID Search](#id-search).

Saving changes to these fields starts an import. Test a question such as "Which battery fits my Makita 6211DWH?" in the Playground.

## Delivery and returns

Include product-specific delivery times and return information in your feed. Unmapped columns can supply this information unless they are [excluded](#excluded-fields). Map shipping costs under **Shipping costs**.

Keep general shipping and return policies in a [knowledge store](https://docs.yourhomie.ai/en/user-guide/knowledge/knowledge-stores.md). Test both general questions and questions about individual products.

## Product documents (PDFs)

If your feed links datasheets, manuals, or other PDFs per product, homie can read them. Under **Product documents**, map the columns with the PDF links and choose the **Document type** of each column: datasheet, manual, safety data sheet, certificate, compatibility list, or other. The documents are treated as written in the market's language. When every variant of a product links the same file, the document belongs to the whole product, otherwise to the variant.

In the market's **Documents** tab you choose how the assistant uses them:

* **Off** — documents are not read; the assistant answers only from the product data.
* **Detail questions only** (default) — the assistant answers questions about a product with passages from its PDFs.
* **Detail questions and finding products** — the assistant also suggests products whose property is only stated in the PDF.

The tab also shows figures such as **Products with PDFs**. For a market that uses the default, documents are read from its next import on.

## Make additional product IDs searchable

Use the **ID Search** card when visitors refer to products by a SKU, variant ID, reference number, or another feed field. Product ID and a mapped GTIN/EAN or manufacturer part number (MPN) field are always included. You can select up to 10 additional fields.

Use one identifier per cell. For example, put `ABC-1` in one cell rather than combining `ABC-1; DEF-2`. To remove additional ID fields, clear the selection and save.

> [!NOTE]
>
> Saving changes to **ID Search** starts an import. New identifiers become available once it completes; searches by product ID and GTIN/EAN keep working in the meantime.

If an identifier finds no product, open **Products** in the catalog and choose **ID search** under **Search**. Check that the identifier exists in the feed, its column is selected, and the latest import has finished.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.