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

# Supplemental data

> Add price lists, promotions, and ratings to a catalog's markets, and use "Applies to" to choose which markets they cover.

Use **Supplemental data** in your catalog to add:

* **Price lists** — prices for a customer group.
* **Promotions** — promotions and coupons.
* **Ratings** — the rating per product.

Supplemental data only adds to products a market already has. It never creates products and does not extend a market's assortment.

## Add a source

Prepare a CSV or XML file available at a URL. Include the product identifiers used in your catalog so homie can match the rows to products.

**1. Choose the source type**

Open the catalog and choose **Supplemental data**, then **Price lists**, **Promotions**, or **Ratings**. Select **Add source**.

**2. Enter the source**

Enter the **Source URL** of a CSV or XML file, choose the **Format** or **Detect automatically**, and select **Load**. Once the file is read, the side panel opens with its columns. If it cannot be read, the dialog shows why; check the URL and format and load it again.

**3. Choose the markets**

Enter a **Name** you can recognize. Under **Applies to**, choose the markets this source adds to.

**4. Match the rows**

Under **Product matching**, the **Product key** sets how the rows match the products (**Product ID**, **GTIN**, or **SKU**). The default market's product key is preselected; choose another one if your file doesn't contain it. Then choose the column with this key in the field of the same name, for example **GTIN**.

**5. Map the columns and save**

Map the columns that belong to the kind of source and save. Errors show at the top of the side panel. After saving, the markets the source applies to are imported again automatically; the change applies afterwards.

After each import, the list shows per market how many rows were matched and how many were not, for example "480 matched · 20 not". If a source has no market selected, the list tells you to choose one.

> [!NOTE]
>
> Keep the complete set of supplemental data in each file. If a product is removed from it, the next successful import removes that source's data for the product. Deleting a source also stops its data from applying.

### Change or remove a source

Open a source to edit it. To replace its file, select **Change** next to **Source URL** and load the new file. Check the mapping again: columns missing from the new file must be assigned again.

If the file cannot be read, check the error beside **Source URL** and correct the URL or format. Use the row menu to delete the source or open its file with **Open source URL**. For repeated load failures, see [Imports and safeguards](https://docs.yourhomie.ai/en/user-guide/knowledge/catalog/imports.md#when-a-file-cannot-be-loaded).

## Price lists

A price list holds separate prices for a customer group, for example retailers, that the assistant shows instead of the market's regular prices. In the side panel, pick a customer group under **Customer group** or create one with **Create a new customer group**, for example `b2b`. The prices apply only in assistants with the same **Customer group** under [Knowledge sources → Products](https://docs.yourhomie.ai/en/user-guide/knowledge/product-data.md#choose-a-catalog-for-an-assistant). The assistant never takes a customer group from the conversation: a visitor who writes "I am a retailer" still sees the regular prices.

Under **Price columns** you map:

* **Price** (required) — the price customers of this customer group pay.
* **Strike-through price** — optionally a higher former or regular price, shown crossed out next to the price.
* **Currency of the prices** — the currency of all prices in the list.
* **Prices are** — **Gross (incl. VAT)** or **Net (excl. VAT)**; trade prices are usually net.
* **VAT rate** — optionally the column with the VAT rate per product. Without it, the assistant names no percentage.
* **Shipping costs** — optionally the column with shipping costs that apply together with these prices, in the same format as in the feed: an amount that applies to every country, for example `4.95`, or entries per country such as `DE:::4.95 EUR,AT:::9.90 EUR` (see [Prices](https://docs.yourhomie.ai/en/user-guide/knowledge/catalog/field-mapping.md#prices)). Without them, the market's shipping costs apply.

Under **Applies to**, a price list can only apply to markets with its currency; other markets cannot be chosen, and the platform names the reason, for example "Different currency (CHF); the price list is in EUR". The gross or net setting may differ from the market's: a list with net prices can apply to a market with gross prices, which is typical for trade prices. The assistant then gives the list's prices plus VAT.

Every product has exactly one price in an answer. If a product has no price in the price list, the assistant shows the market's regular price there, provided the market states the same gross or net setting as the price list; otherwise, and for a market with **Not specified**, such a product has no price. The market always decides which products are available.

The price list's page shows per market how many products had a valid price in the price list at the last import, for example "480 products with a price". Test a product with a group price and one without it in the Playground.

## Promotions

Under **Promotions**, add a CSV or XML file with promotions and coupons: a file with your own columns or a Google Promotions feed.

### Your own columns

Under **Promotion columns**, map:

* **Promotion ID** (required) — the unique ID of the promotion. Rows with the same ID form one promotion.
* **Promotion text** (required) — the text of the promotion as customers should see it, for example “10% off all bike helmets”.
* **Coupon code** — optionally the code customers enter when ordering.
* **Valid from** and **Valid until** — optionally the period of the promotion.

The type and the products of a promotion follow from the data:

* **Type:** with a coupon code, the promotion is a coupon. Without a code, it applies automatically.
* **Products:** the column under **Product matching** names the product a row applies to. If the cell is empty, the promotion applies to all products. For a promotion that covers several products, add one row per product with the same **Promotion ID**. The promotion text, coupon code, and period come from the promotion's first row.

Example, matched by product ID:

| Promotion ID | Promotion text | Coupon code | Valid until | Product ID |
| - | - | - | - | - |
| `helmets10` | 10% off bike helmets | `HELMET10` | `2026-10-31` | `HELMET-M` |
| `helmets10` | 10% off bike helmets | `HELMET10` | `2026-10-31` | `HELMET-L` |
| `shipping` | Free shipping from €50 | | | |

The promotion `helmets10` is a coupon for both helmets up to and including October 31, 2026. The promotion `shipping` applies automatically to all products.

**Dates:** write dates as `DD.MM.YYYY` (for example `31.10.2026`) or `YYYY-MM-DD` (for example `2026-10-31`), optionally with a time such as `31.10.2026 18:00` or `2026-10-31T18:00+01:00`. Values without a time zone are in UTC. A **Valid until** date without a time includes the whole day. Slash formats such as `01/10/2026` are ambiguous (October 1 or January 10); rows with them are skipped.

> [accordion] Use a Google Promotions feed
>
> The platform recognizes a Google Promotions feed by its standard fields and reads them directly: `promotion_id`, `long_title`, `offer_type`, `product_applicability`, `generic_redemption_code`, and `promotion_effective_dates`, plus the product filters `item_id`, `item_group_id`, `brand`, and `product_type`. A filter may have several values, for example several `item_id` values. `promotion_effective_dates` is an ISO 8601 period, for example `2026-10-01T00:00:00+02:00/2026-10-31T23:59:59+01:00`. Do not mix the Google format and your own columns in one file.
>
> Not supported:
>
> * Exclusion filters such as `item_id_exclusion`, `brand_exclusion`, `product_type_exclusion`, and `item_group_id_exclusion`, and filters on `custom_label_0` to `custom_label_4`. Rows with such filters are skipped, so a promotion never applies to more products than intended.
> * Store-only promotions, that is rows whose `redemption_channel` does not include `online`.
> * Linking through `promotion_id` in the product feed.

### Markets and display

a promotion applies in the markets you chose under **Applies to**. When a row contains the Google column `target_country`, that promotion only applies in the chosen markets that serve one of these countries.

The assistant only shows a promotion while it is valid and covers the product. Products in its answers carry their valid promotions. When a visitor asks about current promotions or coupon codes in general, the assistant can also list all valid promotions of the visitor's market, for example only those for one brand. The page shows the number of **Valid promotions**, that is promotions whose validity period includes today. Skipped rows, for example without a promotion ID, with an unreadable date, or without a matching product, count as not matched in the list. The assistant presents promotion texts as information from your shop; it only states a saving in money or percent when it follows from a valid price and strike-through price.

## Ratings

Under **Ratings**, add a CSV or XML file with one row per product. Each row names the product by its product key (product ID, GTIN, or SKU), its average rating, and the number of ratings.

Under **Rating per product** you map:

* **Average rating** (required) — the average as a number, for example `4.5`.
* **Number of ratings** (required) — how many ratings the average is based on, for example `128`. Thousands separators as in `1,234` are allowed.
* **Rating scale from** and **Rating scale to** — the lowest and the highest possible rating in the file. The default is 1 to 5; for a file with scores from 0 to 10, set 0 and 10.

Example matched by GTIN:

| gtin | rating | count |
| - | - | - |
| `4006381333931` | `4.6` | `1,284` |
| `4006381333948` | `3.9` | `57` |

Rows whose rating lies outside the scale or whose number of ratings is not a whole number are skipped.

Customers can ask for a minimum rating, for example "at least 4 out of 5 stars", or ask for the best-rated matching products. In answers, it keeps the scale and the number of ratings from your source.

The page shows the number of **Products with rating**.


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