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

# Markets and countries

> Add markets for countries and languages, assign their countries, add translations, and control which market applies in a conversation.

A market lets you offer the right products and prices to visitors from one or more countries. Each market has its own product feed, currency, availability, and product links. Add [translations](#translations) when you need the same products and prices in another language.

A typical catalog looks like this:

| Market | Countries | Language | Currency |
| - | - | - | - |
| Germany | DE + all other countries (**Default market of the catalog**) | German | EUR |
| Austria | AT | German | EUR |
| Switzerland | CH | German + French as translation | CHF |

Each of these markets reads its own product feed, even when two markets only differ in prices or currency.

## Add a market

**1. Open Markets**

Open the catalog, go to **Markets**, and select **Add market**.

**2. Load the product feed**

In the **The market's product feed** card, enter the URL of the product feed and select **Load product feed**, as described in [Product feed and field mapping](https://docs.yourhomie.ai/en/user-guide/knowledge/catalog/field-mapping.md).

**3. Set up the market**

In the **Market** card, enter under **Name** how the market is named in lists, for example "Germany" or "Switzerland". Check the **Language of the product texts**, choose the countries the market serves under **Countries**, and check the **Currency**. Countries are optional: a market without countries is only used when it is the catalog's default market.

**4. Map the columns and create the market**

Map the columns of the product feed, set how often the market is imported under **Automatic import**, and select **Create market**.

A market's language is the **Language of the product texts** of its product feed. You add more languages as [translations](#translations), optionally with their own product links in that language. You only need a separate market for a language when it has its own prices, assortment, or availability, for example a separate shop at `shop.at/en`.

## Assign countries

The **Markets** page shows each market with its **Countries**, **Language**, **Currency**, **Product key**, number of **Products**, and **Status**. Click a row to open the market.

The last row, **All other countries**, shows with an arrow which market all other countries get, for example "All other countries → Germany (Default market)". It appears as long as visitors from countries without their own market see the default market's products. When these visitors see no products, the row is missing, and the default market's **Countries** column shows **Conversations without a country** instead. Any other market without countries shows **No countries**; no visitor gets it.

Check **Status** to see whether a market is ready or needs attention. If an import fails, open the market and review the error. See [Import status and troubleshooting](https://docs.yourhomie.ai/en/user-guide/knowledge/catalog/imports.md#review-imports).

You choose a market's countries when you add it. Later, you change them in the market's **Settings** tab, in the **General** card. The rules are:

* **One country per language:** a country can have only one market per language. Austria can have a German and an English market, but not two German ones.
* **Default market per country:** when other markets serve a country too, the market settings show the country's default option under **Advanced**, in the **Default market per country** section, for example **Default for Switzerland**. Turn it on to make this market the country's default. A country's default market applies when a visitor's language has no market of its own. When only one market serves a country, there is nothing to choose.
* **Default market of the catalog:** one market is the fallback for conversations without a country. It also serves countries without their own market unless you choose **See no products** for those visitors. The platform makes the catalog's first market its default automatically. You change it in the catalog settings under **Settings → General**, in the **Default market** card under **Default market of the catalog**.

## Which market applies in a conversation

For every product search, the assistant picks the market from two inputs: the **country** and the **language**.

* **Country:** it comes from your page, through the [embed configuration](https://docs.yourhomie.ai/en/api-reference/client/configuration.md) or, on Shopify, from the shop's active market. If the page passes no country, the **Default country** under **Knowledge sources → Products** in the assistant applies. If that is empty too, the catalog's default market applies.
* **Language:** it comes from your website's language settings; otherwise the assistant's default language applies. See [Language resolution](https://docs.yourhomie.ai/en/api-reference/client/configuration.md#language-resolution).

The assistant then picks the market in this order:

**1. Market for country and language**

If there is a market for exactly this country and language, everything comes from it.

**2. Country's default market**

Otherwise the country's default market applies. If it has a translation in the conversation's language, the assistant shows its texts; where the translation lacks a text, it uses the market's base language for that text. Product links come from the translation if it has them, otherwise from the market. Prices and availability always come from this market.

**3. Catalog's default market**

If the country has no market of its own, the catalog's default market applies, unless you chose **See no products** for these visitors.

Prices, availability, and assortment come from the selected market. If a different country's market is used, the assistant can explain which prices it is showing.

**Switching countries in the conversation:** when a visitor asks about another country, for example "What does this cost in Switzerland?", the assistant searches that country's market. It uses the [product key](#product-key) to find the same product there.

> [!NOTE]
>
> The assistant does not convert currencies. Test price questions in each market's currency.

> [!TIP]
>
> In the [Playground](https://docs.yourhomie.ai/en/user-guide/assistants/playground.md), pick a country under **Market** and a language under **Language of the product texts** to see the assistant exactly as visitors of that market see it.

## Countries without their own market

If you only deliver to certain countries, choose **See no products** under **Visitors from countries without their own market** in the **Default market** card of the catalog settings. The assistant then tells these visitors that the shop doesn't deliver to their country. Conversations without a country still use the catalog's default market.

For the catalog's assistants, you can then only pick countries with their own market as **Default country**. When assistants already have a country without a market set there, the catalog settings name them as soon as the option is chosen: their conversations without a country would otherwise get no products. Pick a country with a market for them or leave the field empty.

## Which products are available in a market

Include every product you want the assistant to recommend in that market's feed. Products that exist only in another market are not available for recommendations here.

> [!WARNING]
>
> Each feed update must contain the full assortment for that market. Products removed from the file are also removed from the market after import. See [Smaller files](https://docs.yourhomie.ai/en/user-guide/knowledge/catalog/imports.md#smaller-files).

## Product key

The **Product key** determines how products are recognized within a market and across markets: for [translations](#translations), for [related products and successors](https://docs.yourhomie.ai/en/user-guide/knowledge/catalog/field-mapping.md#related-products), and when someone asks whether a product is also available in Switzerland. A new market uses the **Product ID**. You change the key in the market's **Settings** tab, in the **Product key** card:

* **Product ID** — the ID from the product feed's field mapping.
* **GTIN** — the product's GTIN/EAN.
* **SKU** — your own article number. It can be chosen once a column is mapped to **SKU** in the field mapping.

Products are only recognized across markets that use the same key. When a market uses a different key than the other markets, the **Product key** card in its settings shows **Markets use different product keys**. The product key only links products; it never takes texts, prices, or other data from another market.

## Translations

Translations let customers find products and read their details in another language. The translated product texts and, optionally, links to the product pages in that language come from a file of their own or from additional columns of the market's product feed, for example `title_fr` next to `title`. Prices, availability, and images stay the same as in the original market.

**1. Open Translations**

Open the market, go to the **Translations** tab, and select **Add language**.

**2. Choose the source**

Under **Texts from**, choose where the texts come from:

* **URL**: a file of its own in that language. Enter the **Source URL**, choose the **Format**, and select **Load**. If the file cannot be read, the dialog shows why.
* **This feed**: columns of the market's own product feed. Select **Load**. The translation then uses the product feed's URL; a translation whose **Source URL** is the product feed's URL is always shown as **This feed**. The columns are available once the market has been imported. The columns you map here no longer appear as product details in the market's own language; under **Excluded fields** they show as **Used by a translation**, and saving a change to them imports the market again.

The side panel then opens with the columns. To use another source later, select **Change** next to **Texts from**.

Choose the **Language**. Each market supports up to 20 translations, one per language. Choose a language other than the market's original language.

**3. Match the rows**

For a file (**URL**), choose under **Product matching** the column with the market's product key in the field of the same name, for example **Product ID** (or **GTIN** or **SKU**, depending on what is set for the market). The rows match the market's products by it.

With **This feed** there is nothing to match: every row belongs to the product it describes in the market's feed.

**4. Map the texts**

Choose the columns containing the translated texts. You can also add text fields that are missing from the original market; these are then available only in this language.

* **Product details**: **Product name**, **Description**, **Product URL** (optional, see below), and **Category**. Like in the market's feed, the **Description** may contain HTML.
* **Variants**: **Shared title** and **Variant options** in the form `name:value`, in the same order as in the market's feed.
* **Notice texts**: **Price hint** and **Availability hint**.
* **Advisor notes**: choose the translation's column for each column with advisor notes.
* **Consumer notices**: choose the translation's column for each column with consumer notices. If a translated cell names no type, the notice keeps the type it has in the market.

For a file, check the suggested columns for **Product name** and **Description** before saving. With **This feed**, no columns are suggested: map at least one column in the language, for example `title_fr` as **Product name**. If a translated text or link is missing, the original market's text or link is used.

Your source file can be a complete export in the language or contain only the translated columns and product key. You don't map prices, availability, numbers, or images here; they always come from the market.

**5. Save**

Save the translation. It applies within a few moments, usually without importing the market again. Only when you change which columns of the market's product feed a **This feed** translation reads, the market is imported again first and the translation applies afterwards. Saving without changes starts nothing, and deleting a language removes its texts.

Whenever an import brings new or changed products into the market, all its translations are read again: new products get their texts, and changes in your translation file apply.

### Product URL in the language

A translation belongs to exactly one market. Its **Product URL** is therefore that market's product page in the translation's language. Example: your Switzerland market has a French translation from the export of `shop.ch/fr`. If you map the link column there as **Product URL**, the assistant links French-speaking visitors in Switzerland to `shop.ch/fr`, with the Swiss prices and the Swiss availability.

* The field is optional. Leave it empty if your shop has no separate pages per language, for example because visitors switch the language on the same page. The assistant then links the market's page.
* If the translation has no link for a product or variant, the market's link applies to exactly that product or variant.
* If the file has a link column, such as `link` or `url`, it is already mapped as **Product URL**. Check it or clear the field.
* If the language has its own prices, assortment, or availability, add it as a market of its own instead of a translation.

> [!TIP]
>
> Once the language shows **Active** in the **Translations** tab, open **Products** in the catalog and select the market and translation language. Check a translated name and product link. The **Translations** tab shows how many rows matched a product. If rows were not matched, check the product-key column in your translation file, or with **This feed** that the rows have a value in the mapped columns.

## Move a market to another catalog

In a market's **Settings** tab, use **Move** in the **Change catalog** card to move it to an existing or a new catalog. Its product feed, field mapping, and imports are kept. The dialog names the consequences:

* Assistants of the previous catalog no longer show this market's products.
* The previous catalog's price lists, promotions, and ratings no longer apply to it.
* In the target catalog you choose its countries again.

After the move, open **General** in its **Settings** tab; choose its **Countries** there.

> [!NOTE]
>
> You cannot move or delete the catalog's default market while the catalog has other markets. First choose another default market in the catalog settings.


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