> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/ce/system-management/search/batteryincluded.md).

# BatteryIncluded Search Provider

{% hint style="warning" %}
Contact the [Emporix Support Team](mailto:support@emporix.com) to set up your Emporix tenant in BatteryIncluded before proceeding.
{% endhint %}

You can connect Emporix to BatteryIncluded in one of two ways:

* **Webhook-based (Svix)** – Forward `index-item.updated` and `index-item.deleted` events to BatteryIncluded through Svix endpoints. Use this path when you need custom payload transformation or are not using the native Indexing Service integration. See [Webhook-based search configuration](#webhook-based-search-configuration).
* **Native Indexing Service (recommended)** – Register BatteryIncluded as your indexing provider. Emporix builds product documents, sends create/update/delete requests to BatteryIncluded, and exposes search credentials to your storefront. No webhook or Svix configuration is required. See [Indexing Service configuration](#indexing-service-configuration).

After products are indexed into BatteryIncluded, continue with [BatteryIncluded - search configurations](#batteryincluded-search-configurations) to set up variables, searchable fields, synonyms, facets, and related search behavior.

## Webhook-based search configuration

Before configuring BatteryIncluded endpoints, complete the shared setup in [Search Configuration with Webhooks](/ce/system-management/search/search-configuration.md) and make sure you have the following in place:

* Enabled webhook service
* Enabled `index-item.updated` and `index-item.deleted` events
* [Configured Svix access](/ce/system-management/search/search-configuration.md#webhook-configuration-example-with-svix-shared-strategy)

{% hint style="info" %}
Use the steps below only if you chose the webhook-based path. For most tenants, use the [native Indexing Service](#indexing-service-configuration) instead.
{% endhint %}

### Creating and updating products

{% stepper %}
{% step %}

#### Add an endpoint

In **Endpoints**, choose **Add Endpoint**. Fill in the fields with the following values:

* Endpoint URL - `https://api.batteryincluded.io/api/v1/collections/{BATTERY_INCLUDED_TENANT}/documents/import`
* Description - `BatteryIncluded Create/Update`
* Message filtering - select only the `index-item.updated` event

{% hint style="success" %}
Replace the `{BATTERY_INCLUDED_TENANT}` with the value from the URL address in the BatteryIncluded Portal.

For example, if the URL looks like this `https://portal.batteryincluded.io/#/discover/customer.mytenant`, the `{BATTERY_INCLUDED_TENANT}` value is `customer.mytenant`.
{% endhint %}

<figure><img src="/files/bCK1uuUYPLtLjZ6nWUZo" alt="Svix endpoint configuration for BatteryIncluded create and update"><figcaption><p>Svix endpoint configuration for BatteryIncluded create and update</p></figcaption></figure>
{% endstep %}

{% step %}

#### Save the endpoint

Choose **Create** and check if your configuration was properly saved.
{% endstep %}

{% step %}

#### Add custom headers

Go to the **Advanced** tab, provide the required custom headers:

* Key: `X-BI-API-KEY` Value: Your private integration key

Find the right values for your keys in your connection settings in your BatteryIncluded account.
{% endstep %}

{% step %}

#### Test the configuration

Create a product in Management Dashboard and after a few minutes check if it appears in your index in the BatteryIncluded account. With this configuration, every time when a product is created or updated, the appropriate event is propagated to Svix, transformed and then sent to BatteryIncluded.
{% endstep %}
{% endstepper %}

### Deleting products

{% stepper %}
{% step %}

#### Add an endpoint

In **Endpoints**, choose **Add Endpoint**. Fill in the fields with the following values:

* Endpoint URL - `https://api.batteryincluded.io/api/v1/collections/{BATTERY_INCLUDED_TENANT}/documents/delete`
* Description - `BatteryIncluded Delete`
* Message filtering - select only the `index-item.deleted` event

{% hint style="success" %}
Replace the `{BATTERY_INCLUDED_TENANT}` with the value from the URL address in the BatteryIncluded Portal. For example, if the URL looks like this `https://portal.batteryincluded.io/#/discover/customer.mytenant`, the `{BATTERY_INCLUDED_TENANT}` value is `customer.mytenant`.
{% endhint %}

<figure><img src="/files/og3MVkyR5huIYG90fLcJ" alt="Svix endpoint configuration for BatteryIncluded delete"><figcaption><p>Svix endpoint configuration for BatteryIncluded delete</p></figcaption></figure>
{% endstep %}

{% step %}

#### Save the endpoint

Choose **Create** and check if your configuration was properly saved.
{% endstep %}

{% step %}

#### Add custom header

Go to the **Advanced** tab, provide the required custom headers and enable the transformation feature:

* Key: `X-BI-API-KEY` Value: Your private integration key
  {% endstep %}

{% step %}

#### Enable transformations

In the **Transformations** section, set the **transformation** feature to **enabled**.
{% endstep %}

{% step %}

#### Configure the transformation mapping

In the **Edit transformation** section, change the code to create the right mapping. Modify the HTTP method:

```javascript
  /**
* @param webhook the webhook object
* @param webhook.method destination method. Allowed values: "POST", "PUT"
* @param webhook.url current destination address
* @param webhook.eventType current webhook Event Type
* @param webhook.payload JSON payload
* @param webhook.cancel whether to cancel dispatch of the given webhook
*/
function handler(webhook) {
  // modify the webhook object...

  // convert data
  const payload = [webhook.payload.id]

  webhook.method = "DELETE";
  webhook.payload = payload

  return webhook
}
```

{% endstep %}

{% step %}

#### Save your changes

If the output is correct, save your changes.
{% endstep %}

{% step %}

#### Test the configuration

Delete a product in Management Dashboard and after a few minutes check if it was deleted in your index in the BatteryIncluded account. With this configuration, every time when a product is deleted, the appropriate event is propagated to Svix, transformed and then sent to BatteryIncluded.
{% endstep %}
{% endstepper %}

## Indexing Service configuration

Register BatteryIncluded as your tenant's indexing provider through the Emporix [Indexing Service](/ce/system-management/search/indexing.md). Commerce Engine then manages the full indexing lifecycle — building documents, sending create/update/delete requests to BatteryIncluded, and exposing search credentials to your storefront.

{% hint style="warning" %}
**BatteryIncluded only supports the MERGE strategy.** If your tenant uses the SPLIT strategy and has BatteryIncluded configured as the active provider, BatteryIncluded indexing is silently skipped. See [Indexing strategies](/ce/system-management/search/indexing.md#indexing-strategies) for details.
{% endhint %}

### Enabling BatteryIncluded

To register BatteryIncluded as your indexing provider, send a [Create a new configuration](https://developer.emporix.io/api-references-1/readme/api-reference-18/configuration#post-indexing-tenant-configurations) request with your credentials, or use [Update configuration by provider name](https://developer.emporix.io/api-references-1/readme/api-reference-18/configuration#put-indexing-tenant-configurations-provider) to update an existing configuration.

```bash
curl --location --request POST 'https://api.emporix.io/indexing/{tenant}/configurations' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "active": true,
    "searchKey": "<public integration key>",
    "applicationId": "<customer.mytenant>",
    "indexName": "<customer.mytenant>",
    "writeKey": "<server api key>",
    "provider": "BATTERY_INCLUDED"
}'
```

To update an existing configuration:

```bash
curl --location --request PUT 'https://api.emporix.io/indexing/{tenant}/configurations/BATTERY_INCLUDED' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "active": true,
    "searchKey": "<public integration key>",
    "applicationId": "<customer.mytenant>",
    "indexName": "<customer.mytenant>",
    "writeKey": "<server api key>",
    "provider": "BATTERY_INCLUDED"
}'
```

* `searchKey` — Public integration key from your BatteryIncluded account under **API Connection** → **BI-Webshop**.
* `applicationId` — Name of your tenant in the BatteryIncluded account, for example `customer.featuredemo`.
* `indexName` — You can use the same value as for `applicationId`.
* `writeKey` — Server API Key from your BatteryIncluded account under **API Connection** → **Data-BI**.
* `provider` — Set to `BATTERY_INCLUDED`.

<figure><img src="/files/YffN1EQwo4IrzecK6XaT" alt="BatteryIncluded public integration key under API Connection BI-Webshop"><figcaption><p>BatteryIncluded public integration key (`searchKey`)</p></figcaption></figure>

<figure><img src="/files/Gk8H2hJtXpGeJ9pIOgAQ" alt="BatteryIncluded server API key under API Connection Data-BI"><figcaption><p>BatteryIncluded server API key (`writeKey`)</p></figcaption></figure>

### Setting the MERGE indexing strategy

BatteryIncluded requires the **MERGE** indexing strategy. If your tenant does not have this strategy configured yet, create or update the `indexing_siteAwareFieldsStrategy` configuration through the Emporix Configuration Service. See [Changing index strategy](/ce/system-management/search/indexing.md#changing-index-strategy) for background on SPLIT vs MERGE.

To create the configuration, call the [Creating configurations](https://developer.emporix.io/api-references-1/readme/api-reference-8/tenant-configurations#post-configuration-tenant-configurations) endpoint.

```bash
curl --location 'https://api.emporix.io/configuration/{tenant}/configurations' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '[{
    "key": "indexing_siteAwareFieldsStrategy",
    "secured": true,
    "version": 1,
    "value": {
      "strategy": "MERGE"
    }
  }]'
```

To update an existing configuration, call the [Updating a configuration](https://developer.emporix.io/api-references-1/readme/api-reference-8/tenant-configurations#put-configuration-tenant-configurations-propertykey) endpoint.

```bash
curl --location --request PUT 'https://api.emporix.io/configuration/{tenant}/configurations/indexing_siteAwareFieldsStrategy' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "key": "indexing_siteAwareFieldsStrategy",
    "value": {
      "strategy": "MERGE"
    }
  }'
```

{% hint style="danger" %}
Propagating index strategy changes may take up to 1 hour. See [Changing index strategy](/ce/system-management/search/indexing.md#changing-index-strategy).
{% endhint %}

After the MERGE strategy is in place, trigger a full reindex to push existing product data to BatteryIncluded in the MERGE document format:

```bash
curl --location 'https://api.emporix.io/indexing/{tenant}/reindex' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {token}' \
  --data-raw '{
    "mode": "FULL"
  }'
```

{% hint style="info" %}
Trigger a full reindex whenever indexing configuration changes require existing products to be re-processed — for example after switching to MERGE or updating mixin filtering. See [Reindexing data](/ce/system-management/search/indexing.md#reindexing-data).
{% endhint %}

### Controlling which mixin data is indexed

By default all mixin data is forwarded. You can narrow this down using one of two mutually exclusive options — set at most one per configuration.

{% hint style="warning" %}
Providing both `excludedMixinKeys` and `includedMixinPaths` in the same request is rejected with a `400 Bad Request` error.
{% endhint %}

#### excludedMixinKeys — root-key denylist

List the **top-level mixin key names** you want to block. Each entry is matched exactly against the root name of a mixin; a match drops the entire mixin — both its localized and non-localized portions. Everything else is forwarded unchanged.

Use this option when you have a small number of specific mixins to suppress and want all others to reach the index.

```json
{
  "active": true,
  "provider": "BATTERY_INCLUDED",
  "indexName": "customer.mytenant",
  "writeKey": "your-bi-write-key",
  "excludedMixinKeys": ["internalData", "stagingData"]
}
```

In the example above the `internalData` and `stagingData` mixins are dropped entirely; all other mixins are indexed as normal.

#### includedMixinPaths — glob-path allowlist

List glob patterns selecting which paths inside the mixin tree to **keep**. When this option is non-empty, only the matching paths are forwarded; everything else is dropped. Filtering happens on the raw mixin tree before the localized / non-localized split.

**Glob semantics** (case sensitive, full-path matching):

| Token | Meaning                                                                                                        |
| ----- | -------------------------------------------------------------------------------------------------------------- |
| `*`   | Matches any characters within a single dot-separated segment (never crosses a `.`).                            |
| `**`  | Must appear as a complete segment (e.g. `foo.**` not `foo.**bar`). Matches one or more dot-separated segments. |
| `.`   | Segment separator.                                                                                             |

When a pattern matches a path that points to an object node, the **entire subtree** beneath that node is retained. You only need deeper patterns if you want to keep only specific fields within an object.

**Example** — a tenant has site-aware mixins keyed like `storefront_A_siteAware` and `storefront_B_siteAware`, each containing locale sub-objects:

```json
{
  "storefront_A_siteAware": {
    "en": { "isOnSale": "false", "isVisible": "true" },
    "de": { "isOnSale": "false", "isVisible": "true" }
  },
  "storefront_B_siteAware": {
    "en": { "isOnSale": "true", "isVisible": "true" },
    "de": { "isOnSale": "true", "isVisible": "true" }
  },
  "internalPricingData": { ... }
}
```

To index all site-aware subtrees and nothing else:

```json
{
  "active": true,
  "provider": "BATTERY_INCLUDED",
  "indexName": "customer.mytenant",
  "writeKey": "your-bi-write-key",
  "includedMixinPaths": ["*_siteAware.**"]
}
```

`*_siteAware` matches any root key ending in `_siteAware`; `**` then matches the full subtree beneath it. `internalPricingData` is not matched by any pattern and is dropped entirely.

To keep only the `isOnSale` leaf instead of the whole subtree:

```json
{
  "includedMixinPaths": ["*_siteAware.*.isOnSale"]
}
```

Here `*` matches the locale segment (`en`, `de`, etc.) and the pattern selects only the `isOnSale` field within each locale.

**Malformed patterns are rejected at save time** with a `400 Bad Request` error. The following are invalid:

* Empty string or a pattern that starts or ends with `.`
* Consecutive dots (e.g. `foo..bar`)
* `**` embedded in other characters (e.g. `foo.**bar`)

When `includedMixinPaths` is absent or an empty list, the default behavior applies: all mixins are forwarded (minus any `excludedMixinKeys`).

{% hint style="info" %}
After changing mixin filtering settings, trigger a full reindex so that existing products are re-processed with the new configuration.
{% endhint %}

## BatteryIncluded - index document format

When BatteryIncluded is configured as the native provider, the Indexing Service automatically builds and sends a structured document to the BatteryIncluded API (`POST /api/v1/collections/{indexName}/documents/import`) each time a product or a dependent entity (price, category, availability) is created or updated. All fields are optional and absent fields are omitted from the request body entirely.

The document has the following top-level structure:

| Field                | Type                    | Description                                                                 |
| -------------------- | ----------------------- | --------------------------------------------------------------------------- |
| `id`                 | `string`                | Product identifier.                                                         |
| `type`               | `string`                | Always `"product"`.                                                         |
| `_product`           | object                  | Language-neutral product attributes (core fields, media, mixins).           |
| `_product_i18n`      | `Map<lang, object>`     | Localized product data keyed by BCP-47 language code (e.g. `"en"`, `"de"`). |
| `_product_siteAware` | `Map<siteCode, object>` | Site-specific data keyed by site code (e.g. `"main"`, `"de-store"`).        |

<details>

<summary>See the <code>_product</code> fields (language-neutral attributes)</summary>

| Field                | Type                  | Description                                                                                                                                                                               |
| -------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | `string`              | Product identifier (same as the top-level `id`).                                                                                                                                          |
| `yrn`                | `string`              | Full YRN (Yaas Resource Name) of the product.                                                                                                                                             |
| `code`               | `string`              | Human-readable product code (SKU).                                                                                                                                                        |
| `parentVariantId`    | `string`              | ID of the parent product for variant products.                                                                                                                                            |
| `parentVariantPath`  | `string[]`            | Ordered path of parent IDs from root to direct parent.                                                                                                                                    |
| `productType`        | `string`              | Product type discriminator (e.g. `"BASIC"`, `"VARIANT"`).                                                                                                                                 |
| `dynamicVariantType` | `string`              | Dynamic variant type identifier.                                                                                                                                                          |
| `published`          | `boolean`             | Whether the product is published.                                                                                                                                                         |
| `sellable`           | `boolean`             | Whether the product can be purchased.                                                                                                                                                     |
| `brandId`            | `string`              | Identifier of the associated brand.                                                                                                                                                       |
| `labelIds`           | `string[]`            | List of label identifiers assigned to the product.                                                                                                                                        |
| `categoryIds`        | `string[]`            | Set of category IDs this product is assigned to.                                                                                                                                          |
| `media`              | `object[]`            | Ordered list of product media assets (`url`, `position`, `contentType`, `customAttributes`).                                                                                              |
| `mixins`             | `Map<string, object>` | Non-localized mixin data keyed by mixin name. Controlled by `excludedMixinKeys` (omits listed root keys) or `includedMixinPaths` (retains only matching paths) in the tenant credentials. |
| `createdAt`          | `string (ISO-8601)`   | Product creation timestamp.                                                                                                                                                               |
| `modifiedAt`         | `string (ISO-8601)`   | Product last-modified timestamp.                                                                                                                                                          |

</details>

<details>

<summary>See the <code>_product_i18n</code> entry fields (one entry per language)</summary>

| Field                            | Type                  | Description                                                                                                                                                                                                                                                                         |
| -------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                           | `string`              | Product name in this language. Falls back to the project's default language value if unavailable.                                                                                                                                                                                   |
| `description`                    | `string`              | Product description in this language.                                                                                                                                                                                                                                               |
| `categoryBreadcrumbs`            | `object[]`            | Flat list of cumulative breadcrumb entries for all category assignments in this language. Each entry has `displayPath` (localized path string, e.g. `"Electronics > Audio"`), `idPath` (corresponding category ID path), and `position` (integer depth within the assignment tree). |
| `brand`                          | object                | Brand details resolved in this language (`id`, `name`, `description`, `mediaUrl`).                                                                                                                                                                                                  |
| `labels`                         | `object[]`            | Labels resolved in this language (`id`, `name`, `description`, `mediaUrl`).                                                                                                                                                                                                         |
| `dynamicVariantAttributesValues` | `Map<string, string>` | Dynamic variant attribute values for this language, keyed by attribute key. Each value is the localized display name of the attribute value (falls back to the qualifier if no localized name exists).                                                                              |
| `mixins`                         | `Map<string, object>` | Localized mixin fields extracted from the mixin schema for this language.                                                                                                                                                                                                           |

</details>

<details>

<summary>See the <code>_product_siteAware</code> entry fields (one entry per site)</summary>

| Field           | Type                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `segmentIds`    | `string[]`                  | Customer segment IDs for which this product is visible on this site.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `availability`  | object                      | Stock and availability data: `stockLevel`, `available`, `popularity`, `distributionChannel`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `currencyAware` | `Map<currencyCode, object>` | <p>Currency-level pricing keyed by ISO 4217 currency code (e.g. <code>"USD"</code>, <code>"EUR"</code>). Each entry contains a <code>countryAware</code> map keyed by ISO 3166-1 alpha-2 country code. Each country entry holds:<br>• <code>prices</code> — the full list of all prices for that country. Each price object contains <code>priceId</code>, <code>currency</code>, <code>originalAmount</code>, <code>effectiveAmount</code>, <code>validFrom</code>, <code>validTo</code>, and <code>priceModel</code> (see below).<br>• <code>price</code> — a single price object selected for facet search and sorting: the price with the <strong>lowest <code>effectiveAmount</code></strong> across all prices for that country. Omitted when no price carries an <code>effectiveAmount</code>. Has the same shape as a <code>prices</code> entry.</p> |

Each price object's `priceModel` (when present) contains:

| Field             | Type       | Description                                                                                     |
| ----------------- | ---------- | ----------------------------------------------------------------------------------------------- |
| `priceModelId`    | `string`   | Identifier of the price model.                                                                  |
| `includesTax`     | `boolean`  | Whether the price amounts already include tax.                                                  |
| `measurementUnit` | object     | Base measurement unit the price refers to: `quantity` (number) and `unitCode` (string).         |
| `tierType`        | `string`   | Tier pricing strategy (e.g. `"GRADUATED"`, `"VOLUME"`).                                         |
| `tierValues`      | `object[]` | Tier price rows. Each entry has `id`, `minQuantity` (`quantity`, `unitCode`), and `priceValue`. |

</details>

<details>

<summary>See a full BatteryIncluded example document</summary>

```json
{
  "id": "prod-001",
  "type": "product",
  "_product": {
    "id": "prod-001",
    "yrn": "urn:yaas:saasag:caasproduct:product:myshop;prod-001",
    "code": "PROD-001",
    "parentVariantId": "prod-000",
    "parentVariantPath": ["prod-root", "prod-000"],
    "productType": "VARIANT",
    "dynamicVariantType": "color-size",
    "published": true,
    "sellable": true,
    "brandId": "brand-42",
    "labelIds": ["label-sale"],
    "categoryIds": ["cat-10", "cat-20"],
    "media": [
      {
        "url": "https://cdn.example.com/prod-001.jpg",
        "position": 1,
        "contentType": "image/jpeg",
        "customAttributes": {
          "alt": "Front view"
        }
      }
    ],
    "mixins": {
      "productAttributes": {
        "weight": 1.2
      }
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "modifiedAt": "2024-06-01T08:00:00Z"
  },
  "_product_i18n": {
    "en": {
      "name": "Wireless Headphones",
      "description": "Premium over-ear wireless headphones.",
      "categoryBreadcrumbs": [
        { "displayPath": "Electronics", "idPath": "cat-10", "position": 1 },
        { "displayPath": "Electronics > Audio", "idPath": "cat-10 > cat-20", "position": 2 },
        { "displayPath": "Electronics > Audio > Headphones", "idPath": "cat-10 > cat-20 > cat-30", "position": 3 }
      ],
      "brand": {
        "id": "brand-42",
        "name": "SoundCo",
        "description": "Premium audio equipment.",
        "mediaUrl": "https://cdn.example.com/soundco-logo.png"
      },
      "labels": [
        {
          "id": "label-sale",
          "name": "On Sale",
          "description": "Discounted item",
          "mediaUrl": "https://cdn.example.com/sale-badge.png"
        }
      ],
      "dynamicVariantAttributesValues": {
        "color": "Black",
        "size": "Large"
      },
      "mixins": {
        "productAttributes": {
          "longDescription": "Crystal-clear audio with 30-hour battery life."
        }
      }
    },
    "de": {
      "name": "Kabellose Kopfhörer",
      "description": "Premium Over-Ear-Kopfhörer.",
      "mixins": {
        "productAttributes": {
          "longDescription": "Kristallklarer Klang mit 30 Stunden Akkulaufzeit."
        }
      }
    }
  },
  "_product_siteAware": {
    "main": {
      "segmentIds": ["premium-user"],
      "availability": {
        "stockLevel": 42.0,
        "available": true,
        "popularity": 5,
        "distributionChannel": "ASSORTMENT"
      },
      "currencyAware": {
        "USD": {
          "countryAware": {
            "US": {
              "prices": [
                {
                  "priceId": "price-001",
                  "currency": "USD",
                  "originalAmount": 149.99,
                  "effectiveAmount": 119.99,
                  "validFrom": "2024-01-01T00:00:00Z",
                  "validTo": "2024-12-31T23:59:59Z",
                  "priceModel": {
                    "priceModelId": "pm-001",
                    "includesTax": true,
                    "measurementUnit": {
                      "quantity": 1.0,
                      "unitCode": "piece"
                    },
                    "tierType": "GRADUATED",
                    "tierValues": [
                      {
                        "id": "tier-1",
                        "minQuantity": {
                          "quantity": 1.0,
                          "unitCode": "piece"
                        },
                        "priceValue": 119.99
                      },
                      {
                        "id": "tier-2",
                        "minQuantity": {
                          "quantity": 10.0,
                          "unitCode": "piece"
                        },
                        "priceValue": 99.99
                      }
                    ]
                  }
                },
                {
                  "priceId": "price-003",
                  "currency": "USD",
                  "originalAmount": 99.99,
                  "effectiveAmount": 89.99,
                  "priceModel": {
                    "priceModelId": "pm-002",
                    "includesTax": true,
                    "measurementUnit": {
                      "quantity": 1.0,
                      "unitCode": "piece"
                    }
                  }
                }
              ],
              "price": {
                "priceId": "price-003",
                "currency": "USD",
                "originalAmount": 99.99,
                "effectiveAmount": 89.99,
                "priceModel": {
                  "priceModelId": "pm-002",
                  "includesTax": true,
                  "measurementUnit": {
                    "quantity": 1.0,
                    "unitCode": "piece"
                  }
                }
              }
            }
          }
        },
        "EUR": {
          "countryAware": {
            "DE": {
              "prices": [
                {
                  "priceId": "price-002",
                  "currency": "EUR",
                  "originalAmount": 139.99,
                  "effectiveAmount": 109.99
                }
              ],
              "price": {
                "priceId": "price-002",
                "currency": "EUR",
                "originalAmount": 139.99,
                "effectiveAmount": 109.99
              }
            }
          }
        }
      }
    }
  }
}
```

</details>

## BatteryIncluded - search configurations

After Emporix indexes products through the native Indexing Service, configure search behavior in the BatteryIncluded portal so results respect locale, site, and country context.

### Variables

Variables tell BatteryIncluded which query parameters (`locale`, `siteAware`, `currencyAware`, and `countryAware`) to apply when reading indexed product documents. With variables configured, search and explore requests return scoped payloads instead of the full multi-locale, multi-site document.

{% stepper %}
{% step %}

#### Add schema variables

In the BatteryIncluded portal, go to **Schema** → **Variables** and choose **Add variable**. Create variables for `locale`, `siteAware`, `currencyAware`, and `countryAware`. Map each variable to the matching parent path in the imported schema (for example `locale` under `_product_i18n`, `siteAware` under `_product_siteAware`).

<figure><img src="/files/Jkc6QKyNcIDUdGT78nNR" alt="BatteryIncluded schema variables for locale, siteAware, currencyAware, and countryAware"><figcaption><p>BatteryIncluded schema variables for locale, siteAware, currencyAware, and countryAware</p></figcaption></figure>
{% endstep %}

{% step %}

#### Save your changes

Choose **Save**. Product data returned by search is filtered according to the active variable values.
{% endstep %}

{% step %}

#### Configure browse query

Go to **Schema** → **Browse query**. Under **Filters**, add the fields you want to scope with your variables (for example localized mixins, brand name, category breadcrumbs, and price). Use the **Try it** panel to test requests with different `locale`, `siteAware`, `currencyAware`, and `countryAware` values.

<figure><img src="/files/tDAuQPGneQ8hUkmwW6Cf" alt="BatteryIncluded Schema Browse query filters and Try it panel"><figcaption><p>BatteryIncluded Schema Browse query filters and Try it panel</p></figcaption></figure>
{% endstep %}
{% endstepper %}

The examples below show how the same product document is shaped with and without variables.

{% tabs %}
{% tab title="With variables" %}
When variables are active, BatteryIncluded returns a flattened document scoped to the requested locale, site, and country — for example a single `_product_i18n` object instead of a map of language codes.

<details>

<summary>See an example document with variables</summary>

```json
{
            "_product": {
              "brandId": "6839879e72421575a8197b52",
              "categoryIds": [
                "e18de470-9415-48cf-8d40-8a3fcdb9fd53",
                "9d449cf1-0ae5-455e-ab54-3ce15ec18d6e",
                "3a7e5b73-22a8-4a04-a9a6-ff2db5ddbf92",
                "24d59403-24f8-443f-a6f4-833503e6075e",
                "05620e54-a379-49de-a2b0-b3ab1bd0acc5",
                "3dd47373-16f0-499d-9b49-3c39175518ff",
                "8d5dc3dd-3926-4495-b041-234bba4ec81d",
                "812358ba-6327-4195-ac6b-bf77e1fb9718",
                "ad1bfeab-8e01-4fdd-98b4-4ca490b4ebcb",
                "3481bc5e-6bb5-45c7-81ea-9cc6fd0b0e88"
              ],
              "code": "leaf",
              "createdAt": "2026-05-19T07:01:23.363Z",
              "dynamicVariantType": "VariantTypeRoot",
              "id": "6a0c0ac38793283a1ebfa888",
              "labelIds": [
                "683987a072421575a8197b53"
              ],
              "media": [
                {
                  "contentType": "image/png",
                  "customAttributes": {
                    "height": 629,
                    "name": "Screenshot 2026-05-21 at 09.15.34.png",
                    "sizeKB": 527.380859375,
                    "width": 463
                  },
                  "url": "https://res.cloudinary.com/saas-ag/image/upload/v1779363569/showcasedev/media/6a0eeef0d523f84b570bd005"
                }
              ],
              "mixins": {
                "usp": {
                  "usp": [
                    {
                      "icon": "hhhhh"
                    }
                  ]
                }
              },
              "modifiedAt": "2026-05-25T11:29:12.577Z",
              "parentVariantId": "6a0c0a6c8793283a1ebfa887",
              "parentVariantPath": [
                "6a0c0a6c8793283a1ebfa887",
                "6a0c0a3a8793283a1ebfa886"
              ],
              "productType": "DYNAMIC_VARIANT",
              "published": true,
              "sellable": false,
              "yrn": "urn:yaas:saasag:caasproduct:product:showcasedev;6a0c0ac38793283a1ebfa888"
            },
            "_product_i18n": {
              "brand": {
                "description": "<p>Victron Energy</p>",
                "id": "6839879e72421575a8197b52",
                "mediaUrl": "http://res.cloudinary.com/saas-ag/image/upload/v1748600735/showcase/media/6839879fb5837704f715e9d0",
                "name": "Victron Energy"
              },
              "categories": {
                "breadcrumbs": [
                  "Metals",
                  "Metals > Tubes",
                  "Electrical supplies",
                  "Electrical supplies > Power generation",
                  "Electrical supplies > Power generation > Portable power stations",
                  "Electrical supplies > Power generation > Portable power stations > Power station accessories",
                  "Home",
                  "Home > Garage",
                  "Home",
                  "Home > Furniture",
                  "Home > Furniture > Sofaa"
                ],
                "hierarchy": [
                  {
                    "id": "3a7e5b73-22a8-4a04-a9a6-ff2db5ddbf92",
                    "name": "Tubes",
                    "parent": {
                      "id": "812358ba-6327-4195-ac6b-bf77e1fb9718",
                      "name": "Metals"
                    }
                  },
                  {
                    "id": "8d5dc3dd-3926-4495-b041-234bba4ec81d",
                    "name": "Power station accessories",
                    "parent": {
                      "id": "ad1bfeab-8e01-4fdd-98b4-4ca490b4ebcb",
                      "name": "Portable power stations",
                      "parent": {
                        "id": "9d449cf1-0ae5-455e-ab54-3ce15ec18d6e",
                        "name": "Power generation",
                        "parent": {
                          "id": "e18de470-9415-48cf-8d40-8a3fcdb9fd53",
                          "name": "Electrical supplies"
                        }
                      }
                    }
                  },
                  {
                    "id": "3481bc5e-6bb5-45c7-81ea-9cc6fd0b0e88",
                    "name": "Garage",
                    "parent": {
                      "id": "05620e54-a379-49de-a2b0-b3ab1bd0acc5",
                      "name": "Home"
                    }
                  },
                  {
                    "id": "3dd47373-16f0-499d-9b49-3c39175518ff",
                    "name": "Sofaa",
                    "parent": {
                      "id": "24d59403-24f8-443f-a6f4-833503e6075e",
                      "name": "Furniture",
                      "parent": {
                        "id": "05620e54-a379-49de-a2b0-b3ab1bd0acc5",
                        "name": "Home"
                      }
                    }
                  }
                ]
              },
              "description": "Desc en334r\n",
              "dynamicVariantAttributesValues": {
                "ScrewCoating": "Zinc Plated",
                "screwHeaderType": "X plated"
              },
              "labels": [
                {
                  "description": "<p>Promotion</p>",
                  "id": "683987a072421575a8197b53",
                  "mediaUrl": "http://res.cloudinary.com/saas-ag/image/upload/v1748600737/showcase/media/683987a0f1ce3e61a7ad9dc5",
                  "name": "Promotion"
                }
              ],
              "mixins": {
                "usp": {
                  "usp": [
                    {
                      "description": "Value ENxxxx"
                    }
                  ]
                }
              },
              "name": "Name enxz"
            },
            "_product_siteAware": {
              "availability": {
                "available": false,
                "distributionChannel": "ASSORTMENT",
                "popularity": 0,
                "stockLevel": 3
              },
              "countryAware": {
                "price": {
                  "currency": "EUR",
                  "effectiveAmount": 23.05,
                  "originalAmount": 23.05,
                  "priceId": "6a0c0b74c5b457004b86f4b0",
                  "priceModel": {
                    "includesTax": false,
                    "measurementUnit": {
                      "quantity": 1,
                      "unitCode": "pc"
                    },
                    "priceModelId": "63402c86af907617bb4e1234",
                    "tierType": "BASIC",
                    "tierValues": [
                      {
                        "id": "63402c86af907617bb4e9826",
                        "minQuantity": {
                          "quantity": 0,
                          "unitCode": "pc"
                        },
                        "priceValue": 23.05
                      }
                    ]
                  }
                }
              },
              "segmentIds": [
                "testGrusio"
              ]
            },
            "id": "6a0c0ac38793283a1ebfa888",
            "type": "product"
          }

```

</details>
{% endtab %}

{% tab title="Without variables" %}
Without variables, the full indexed document is returned, including all locales under `_product_i18n` and all sites under `_product_siteAware`.

<details>

<summary>See an example document without variables</summary>

```json
{
            "_product": {
              "brandId": "6839879e72421575a8197b52",
              "categoryIds": [
                "e18de470-9415-48cf-8d40-8a3fcdb9fd53",
                "9d449cf1-0ae5-455e-ab54-3ce15ec18d6e",
                "3a7e5b73-22a8-4a04-a9a6-ff2db5ddbf92",
                "24d59403-24f8-443f-a6f4-833503e6075e",
                "05620e54-a379-49de-a2b0-b3ab1bd0acc5",
                "3dd47373-16f0-499d-9b49-3c39175518ff",
                "8d5dc3dd-3926-4495-b041-234bba4ec81d",
                "812358ba-6327-4195-ac6b-bf77e1fb9718",
                "ad1bfeab-8e01-4fdd-98b4-4ca490b4ebcb",
                "3481bc5e-6bb5-45c7-81ea-9cc6fd0b0e88"
              ],
              "code": "leaf",
              "createdAt": "2026-05-19T07:01:23.363Z",
              "dynamicVariantType": "VariantTypeRoot",
              "id": "6a0c0ac38793283a1ebfa888",
              "labelIds": [
                "683987a072421575a8197b53"
              ],
              "media": [
                {
                  "contentType": "image/png",
                  "customAttributes": {
                    "height": 629,
                    "name": "Screenshot 2026-05-21 at 09.15.34.png",
                    "sizeKB": 527.380859375,
                    "width": 463
                  },
                  "url": "https://res.cloudinary.com/saas-ag/image/upload/v1779363569/showcasedev/media/6a0eeef0d523f84b570bd005"
                }
              ],
              "mixins": {
                "usp": {
                  "usp": [
                    {
                      "icon": "hhhhh"
                    }
                  ]
                }
              },
              "modifiedAt": "2026-05-25T11:29:12.577Z",
              "parentVariantId": "6a0c0a6c8793283a1ebfa887",
              "parentVariantPath": [
                "6a0c0a6c8793283a1ebfa887",
                "6a0c0a3a8793283a1ebfa886"
              ],
              "productType": "DYNAMIC_VARIANT",
              "published": true,
              "sellable": false,
              "yrn": "urn:yaas:saasag:caasproduct:product:showcasedev;6a0c0ac38793283a1ebfa888"
            },
            "_product_i18n": {
              "de": {
                "brand": {
                  "description": "<p>Victron Energy</p>",
                  "id": "6839879e72421575a8197b52",
                  "mediaUrl": "http://res.cloudinary.com/saas-ag/image/upload/v1748600735/showcase/media/6839879fb5837704f715e9d0",
                  "name": "Victron Energy"
                },
                "categories": {
                  "breadcrumbs": [
                    "Metalle",
                    "Metalle > Rohre",
                    "Electrical supplies",
                    "Electrical supplies > Power generation",
                    "Electrical supplies > Power generation > Portable power stations",
                    "Electrical supplies > Power generation > Portable power stations > Power station accessories",
                    "Home",
                    "Home > Garage",
                    "Home",
                    "Home > Möbel",
                    "Home > Möbel > Sofa"
                  ],
                  "hierarchy": [
                    {
                      "id": "3a7e5b73-22a8-4a04-a9a6-ff2db5ddbf92",
                      "name": "Rohre",
                      "parent": {
                        "id": "812358ba-6327-4195-ac6b-bf77e1fb9718",
                        "name": "Metalle"
                      }
                    },
                    {
                      "id": "8d5dc3dd-3926-4495-b041-234bba4ec81d",
                      "name": "Power station accessories",
                      "parent": {
                        "id": "ad1bfeab-8e01-4fdd-98b4-4ca490b4ebcb",
                        "name": "Portable power stations",
                        "parent": {
                          "id": "9d449cf1-0ae5-455e-ab54-3ce15ec18d6e",
                          "name": "Power generation",
                          "parent": {
                            "id": "e18de470-9415-48cf-8d40-8a3fcdb9fd53",
                            "name": "Electrical supplies"
                          }
                        }
                      }
                    },
                    {
                      "id": "3481bc5e-6bb5-45c7-81ea-9cc6fd0b0e88",
                      "name": "Garage",
                      "parent": {
                        "id": "05620e54-a379-49de-a2b0-b3ab1bd0acc5",
                        "name": "Home"
                      }
                    },
                    {
                      "id": "3dd47373-16f0-499d-9b49-3c39175518ff",
                      "name": "Sofa",
                      "parent": {
                        "id": "24d59403-24f8-443f-a6f4-833503e6075e",
                        "name": "Möbel",
                        "parent": {
                          "id": "05620e54-a379-49de-a2b0-b3ab1bd0acc5",
                          "name": "Home"
                        }
                      }
                    }
                  ]
                },
                "description": "Desc de",
                "dynamicVariantAttributesValues": {
                  "ScrewCoating": "Zinc Plated DE",
                  "screwHeaderType": "X plated"
                },
                "labels": [
                  {
                    "description": "<p>Promotion</p>",
                    "id": "683987a072421575a8197b53",
                    "mediaUrl": "http://res.cloudinary.com/saas-ag/image/upload/v1748600737/showcase/media/683987a0f1ce3e61a7ad9dc5",
                    "name": "Promotion"
                  }
                ],
                "mixins": {
                  "usp": {
                    "usp": [
                      {
                        "description": "Name DEd"
                      }
                    ]
                  }
                },
                "name": "Name dexs"
              },
              "en": {
                "brand": {
                  "description": "<p>Victron Energy</p>",
                  "id": "6839879e72421575a8197b52",
                  "mediaUrl": "http://res.cloudinary.com/saas-ag/image/upload/v1748600735/showcase/media/6839879fb5837704f715e9d0",
                  "name": "Victron Energy"
                },
                "categories": {
                  "breadcrumbs": [
                    "Metals",
                    "Metals > Tubes",
                    "Electrical supplies",
                    "Electrical supplies > Power generation",
                    "Electrical supplies > Power generation > Portable power stations",
                    "Electrical supplies > Power generation > Portable power stations > Power station accessories",
                    "Home",
                    "Home > Garage",
                    "Home",
                    "Home > Furniture",
                    "Home > Furniture > Sofaa"
                  ],
                  "hierarchy": [
                    {
                      "id": "3a7e5b73-22a8-4a04-a9a6-ff2db5ddbf92",
                      "name": "Tubes",
                      "parent": {
                        "id": "812358ba-6327-4195-ac6b-bf77e1fb9718",
                        "name": "Metals"
                      }
                    },
                    {
                      "id": "8d5dc3dd-3926-4495-b041-234bba4ec81d",
                      "name": "Power station accessories",
                      "parent": {
                        "id": "ad1bfeab-8e01-4fdd-98b4-4ca490b4ebcb",
                        "name": "Portable power stations",
                        "parent": {
                          "id": "9d449cf1-0ae5-455e-ab54-3ce15ec18d6e",
                          "name": "Power generation",
                          "parent": {
                            "id": "e18de470-9415-48cf-8d40-8a3fcdb9fd53",
                            "name": "Electrical supplies"
                          }
                        }
                      }
                    },
                    {
                      "id": "3481bc5e-6bb5-45c7-81ea-9cc6fd0b0e88",
                      "name": "Garage",
                      "parent": {
                        "id": "05620e54-a379-49de-a2b0-b3ab1bd0acc5",
                        "name": "Home"
                      }
                    },
                    {
                      "id": "3dd47373-16f0-499d-9b49-3c39175518ff",
                      "name": "Sofaa",
                      "parent": {
                        "id": "24d59403-24f8-443f-a6f4-833503e6075e",
                        "name": "Furniture",
                        "parent": {
                          "id": "05620e54-a379-49de-a2b0-b3ab1bd0acc5",
                          "name": "Home"
                        }
                      }
                    }
                  ]
                },
                "description": "Desc en334r\n",
                "dynamicVariantAttributesValues": {
                  "ScrewCoating": "Zinc Plated",
                  "screwHeaderType": "X plated"
                },
                "labels": [
                  {
                    "description": "<p>Promotion</p>",
                    "id": "683987a072421575a8197b53",
                    "mediaUrl": "http://res.cloudinary.com/saas-ag/image/upload/v1748600737/showcase/media/683987a0f1ce3e61a7ad9dc5",
                    "name": "Promotion"
                  }
                ],
                "mixins": {
                  "usp": {
                    "usp": [
                      {
                        "description": "Value ENxxxx"
                      }
                    ]
                  }
                },
                "name": "Name enxz"
              },
              "pl": {
                "brand": {
                  "description": "<p>Victron Energy</p>",
                  "id": "6839879e72421575a8197b52",
                  "mediaUrl": "http://res.cloudinary.com/saas-ag/image/upload/v1748600735/showcase/media/6839879fb5837704f715e9d0",
                  "name": "Victron Energy"
                },
                "categories": {
                  "breadcrumbs": [
                    "Metals",
                    "Metals > Tubes",
                    "Electrical supplies",
                    "Electrical supplies > Power generation",
                    "Electrical supplies > Power generation > Portable power stations",
                    "Electrical supplies > Power generation > Portable power stations > Power station accessories",
                    "Home",
                    "Home > Garage",
                    "Home",
                    "Home > Furniture",
                    "Home > Furniture > Sofaa"
                  ],
                  "hierarchy": [
                    {
                      "id": "3a7e5b73-22a8-4a04-a9a6-ff2db5ddbf92",
                      "name": "Tubes",
                      "parent": {
                        "id": "812358ba-6327-4195-ac6b-bf77e1fb9718",
                        "name": "Metals"
                      }
                    },
                    {
                      "id": "8d5dc3dd-3926-4495-b041-234bba4ec81d",
                      "name": "Power station accessories",
                      "parent": {
                        "id": "ad1bfeab-8e01-4fdd-98b4-4ca490b4ebcb",
                        "name": "Portable power stations",
                        "parent": {
                          "id": "9d449cf1-0ae5-455e-ab54-3ce15ec18d6e",
                          "name": "Power generation",
                          "parent": {
                            "id": "e18de470-9415-48cf-8d40-8a3fcdb9fd53",
                            "name": "Electrical supplies"
                          }
                        }
                      }
                    },
                    {
                      "id": "3481bc5e-6bb5-45c7-81ea-9cc6fd0b0e88",
                      "name": "Garage",
                      "parent": {
                        "id": "05620e54-a379-49de-a2b0-b3ab1bd0acc5",
                        "name": "Home"
                      }
                    },
                    {
                      "id": "3dd47373-16f0-499d-9b49-3c39175518ff",
                      "name": "Sofaa",
                      "parent": {
                        "id": "24d59403-24f8-443f-a6f4-833503e6075e",
                        "name": "Furniture",
                        "parent": {
                          "id": "05620e54-a379-49de-a2b0-b3ab1bd0acc5",
                          "name": "Home"
                        }
                      }
                    }
                  ]
                },
                "description": "Desc PL",
                "dynamicVariantAttributesValues": {
                  "ScrewCoating": "Zinc Plated",
                  "screwHeaderType": "X plated"
                },
                "labels": [
                  {
                    "description": "<p>Promotion</p>",
                    "id": "683987a072421575a8197b53",
                    "mediaUrl": "http://res.cloudinary.com/saas-ag/image/upload/v1748600737/showcase/media/683987a0f1ce3e61a7ad9dc5",
                    "name": "Promotion"
                  }
                ],
                "mixins": {
                  "usp": {
                    "usp": [
                      {
                        "description": "Something PL"
                      }
                    ]
                  }
                },
                "name": "Name PL"
              }
            },
            "_product_siteAware": {
              "brand1": {
                "availability": {
                  "available": false,
                  "popularity": 0,
                  "stockLevel": 1
                },
                "countryAware": {
                  "DE": {
                    "price": {
                      "currency": "EUR",
                      "effectiveAmount": 23.05,
                      "originalAmount": 23.05,
                      "priceId": "6a0c0b74c5b457004b86f4b0",
                      "priceModel": {
                        "includesTax": false,
                        "measurementUnit": {
                          "quantity": 1,
                          "unitCode": "pc"
                        },
                        "priceModelId": "63402c86af907617bb4e1234",
                        "tierType": "BASIC",
                        "tierValues": [
                          {
                            "id": "63402c86af907617bb4e9826",
                            "minQuantity": {
                              "quantity": 0,
                              "unitCode": "pc"
                            },
                            "priceValue": 23.05
                          }
                        ]
                      }
                    }
                  }
                }
              },
              "dealer1": {
                "availability": {
                  "available": false,
                  "popularity": 0,
                  "stockLevel": 1
                },
                "countryAware": {
                  "DE": {
                    "price": {
                      "currency": "EUR",
                      "effectiveAmount": 23.05,
                      "originalAmount": 23.05,
                      "priceId": "6a0c0b74c5b457004b86f4b0",
                      "priceModel": {
                        "includesTax": false,
                        "measurementUnit": {
                          "quantity": 1,
                          "unitCode": "pc"
                        },
                        "priceModelId": "63402c86af907617bb4e1234",
                        "tierType": "BASIC",
                        "tierValues": [
                          {
                            "id": "63402c86af907617bb4e9826",
                            "minQuantity": {
                              "quantity": 0,
                              "unitCode": "pc"
                            },
                            "priceValue": 23.05
                          }
                        ]
                      }
                    }
                  }
                }
              },
              "fw-site": {
                "availability": {
                  "available": false,
                  "popularity": 0,
                  "stockLevel": 1
                },
                "countryAware": {
                  "DE": {
                    "price": {
                      "currency": "EUR",
                      "effectiveAmount": 23.05,
                      "originalAmount": 23.05,
                      "priceId": "6a0c0b74c5b457004b86f4b0",
                      "priceModel": {
                        "includesTax": false,
                        "measurementUnit": {
                          "quantity": 1,
                          "unitCode": "pc"
                        },
                        "priceModelId": "63402c86af907617bb4e1234",
                        "tierType": "BASIC",
                        "tierValues": [
                          {
                            "id": "63402c86af907617bb4e9826",
                            "minQuantity": {
                              "quantity": 0,
                              "unitCode": "pc"
                            },
                            "priceValue": 23.05
                          }
                        ]
                      }
                    }
                  },
                  "FR": {
                    "price": {
                      "currency": "EUR",
                      "effectiveAmount": 3,
                      "originalAmount": 3,
                      "priceId": "6a0c0b8cc5b457004b86f4b1",
                      "priceModel": {
                        "includesTax": false,
                        "measurementUnit": {
                          "quantity": 1,
                          "unitCode": "pc"
                        },
                        "priceModelId": "63402c86af907617bb4e1234",
                        "tierType": "BASIC",
                        "tierValues": [
                          {
                            "id": "63402c86af907617bb4e9826",
                            "minQuantity": {
                              "quantity": 0,
                              "unitCode": "pc"
                            },
                            "priceValue": 3
                          }
                        ]
                      }
                    }
                  }
                }
              },
              "main": {
                "availability": {
                  "available": false,
                  "popularity": 0
                },
                "countryAware": {
                  "DE": {
                    "price": {
                      "currency": "EUR",
                      "effectiveAmount": 23.05,
                      "originalAmount": 23.05,
                      "priceId": "6a0c0b74c5b457004b86f4b0",
                      "priceModel": {
                        "includesTax": false,
                        "measurementUnit": {
                          "quantity": 1,
                          "unitCode": "pc"
                        },
                        "priceModelId": "63402c86af907617bb4e1234",
                        "tierType": "BASIC",
                        "tierValues": [
                          {
                            "id": "63402c86af907617bb4e9826",
                            "minQuantity": {
                              "quantity": 0,
                              "unitCode": "pc"
                            },
                            "priceValue": 23.05
                          }
                        ]
                      }
                    }
                  }
                }
              },
              "us-branch": {
                "availability": {
                  "available": false,
                  "distributionChannel": "ASSORTMENT",
                  "popularity": 0,
                  "stockLevel": 3
                },
                "countryAware": {
                  "DE": {
                    "price": {
                      "currency": "EUR",
                      "effectiveAmount": 23.05,
                      "originalAmount": 23.05,
                      "priceId": "6a0c0b74c5b457004b86f4b0",
                      "priceModel": {
                        "includesTax": false,
                        "measurementUnit": {
                          "quantity": 1,
                          "unitCode": "pc"
                        },
                        "priceModelId": "63402c86af907617bb4e1234",
                        "tierType": "BASIC",
                        "tierValues": [
                          {
                            "id": "63402c86af907617bb4e9826",
                            "minQuantity": {
                              "quantity": 0,
                              "unitCode": "pc"
                            },
                            "priceValue": 23.05
                          }
                        ]
                      }
                    }
                  },
                  "FR": {
                    "price": {
                      "currency": "EUR",
                      "effectiveAmount": 3,
                      "originalAmount": 3,
                      "priceId": "6a0c0b8cc5b457004b86f4b1",
                      "priceModel": {
                        "includesTax": false,
                        "measurementUnit": {
                          "quantity": 1,
                          "unitCode": "pc"
                        },
                        "priceModelId": "63402c86af907617bb4e1234",
                        "tierType": "BASIC",
                        "tierValues": [
                          {
                            "id": "63402c86af907617bb4e9826",
                            "minQuantity": {
                              "quantity": 0,
                              "unitCode": "pc"
                            },
                            "priceValue": 3
                          }
                        ]
                      }
                    }
                  },
                  "US": {
                    "price": {
                      "currency": "EUR",
                      "effectiveAmount": 4,
                      "originalAmount": 4,
                      "priceId": "6a0c0b9dff1c894000023398",
                      "priceModel": {
                        "includesTax": false,
                        "measurementUnit": {
                          "quantity": 1,
                          "unitCode": "pc"
                        },
                        "priceModelId": "63402c86af907617bb4e1234",
                        "tierType": "BASIC",
                        "tierValues": [
                          {
                            "id": "63402c86af907617bb4e9826",
                            "minQuantity": {
                              "quantity": 0,
                              "unitCode": "pc"
                            },
                            "priceValue": 4
                          }
                        ]
                      }
                    }
                  }
                },
                "segmentIds": [
                  "testGrusio"
                ]
              }
            },
            "id": "6a0c0ac38793283a1ebfa888",
            "type": "product"
          }
```

</details>
{% endtab %}
{% endtabs %}

### Searchable fields

Define which indexed fields BatteryIncluded searches, along with priority and typo tolerance. When the `locale` variable is configured, reference localized fields through the variable in the field path (for example `_product_i18n > locale > name`).

{% stepper %}
{% step %}

#### Add search fields

In the BatteryIncluded portal, go to **Relevance** → **Search** and choose **Add search field**. Select the fields you want to include in full-text search and configure priority and typo settings as needed.

<figure><img src="/files/2BT6pm1XLGVCm6wTzAAl" alt="BatteryIncluded Relevance Search tab with searchable fields, priority, and typo settings"><figcaption><p>BatteryIncluded Relevance Search tab with searchable fields, priority, and typo settings</p></figcaption></figure>
{% endstep %}

{% step %}

#### Save your changes

Choose **Save** to apply the searchable field configuration.
{% endstep %}
{% endstepper %}

### Synonyms

Synonyms help shoppers find products without entering an exact product name. For example, map `battery` to `accumulator` so that both terms return the same results.

{% hint style="warning" %}
BatteryIncluded requires at least one synonym entry before **Explore** works. Add synonyms in **Relevance** → **Synonyms**.
{% endhint %}

<figure><img src="/files/1iHRndBHefSuJd5E9pfi" alt="BatteryIncluded synonym dictionary"><figcaption><p>BatteryIncluded synonym dictionary</p></figcaption></figure>

### Category tree

BatteryIncluded expects category breadcrumbs as human-readable names separated by `>` (for example `Electronics > Audio > Headphones`). To use Emporix category breadcrumbs as facets and display them in Explore, mark the field as filterable and map it in the Explore setup.

{% stepper %}
{% step %}

#### Enable the filterable setting

In the BatteryIncluded portal, go to **Schema** → **Import**, open `_product_i18n` → `{locale}` → `categories` → `breadcrumbs`, and switch on **Filterable**.

<figure><img src="/files/3tATehSeSuYhF8Ca61ts" alt="Filterable setting for category breadcrumbs in BatteryIncluded schema"><figcaption><p>Filterable setting for category breadcrumbs in BatteryIncluded schema</p></figcaption></figure>
{% endstep %}

{% step %}

#### Configure Explore setup

Go to **Explore** and choose the **Setup** icon. After setup is complete, select a locale in Explore to see the category list with product counts.

<figure><img src="/files/5oeyWPGp0F3c7axXTCbk" alt="Explore setup icon in BatteryIncluded"><figcaption><p>Explore setup icon in BatteryIncluded</p></figcaption></figure>
{% endstep %}

{% step %}

#### Map image and category fields

In the **More** tab, configure the display fields and save your changes.

* Image — `_product.media0.url`
* Category — `_product_i18n.categories.breadcrumbs`

<figure><img src="/files/ReZ9AOROCCjtt6eqVdYY" alt="Explore More settings for image and category fields"><figcaption><p>Explore More settings for image and category fields</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### Variants

You can group related products by shared attributes so shoppers can switch between variants in search results.

{% stepper %}
{% step %}

#### Configure variant grouping

In the BatteryIncluded portal, go to **Relevance** → **Variants** and set up grouping by the relevant attributes.

<figure><img src="/files/vIb1REBCE1I4EAJlBF4U" alt="BatteryIncluded variants setup under Relevance"><figcaption><p>BatteryIncluded variants setup under Relevance</p></figcaption></figure>
{% endstep %}

{% step %}

#### Check variants in Explore

Open **Explore** → **Search**. When variants exist for a product, they appear next to the product with a count indicator.

<figure><img src="/files/X7uu6LQt50LYm6pWuw8V" alt="Product variants shown in BatteryIncluded Explore Search"><figcaption><p>Product variants shown in BatteryIncluded Explore Search</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### Facets

Any filterable field can be used as a facet. Category breadcrumbs were already marked as filterable in [Category tree](#category-tree). The steps below show how to add a price range facet and optional dynamic attribute filters.

{% stepper %}
{% step %}

#### Make price filterable

In **Schema** → **Import**, open `_product_siteAware` → `{siteAware}` → `currencyAware` → `{countryAware}`, and set `price.effectiveAmount` to **Filterable**. Change the field type to **float**.

<figure><img src="/files/6kvZjE0u9LZR8nJUqbXx" alt="Filterable float setting for effectiveAmount price field"><figcaption><p>Filterable float setting for effectiveAmount price field</p></figcaption></figure>
{% endstep %}

{% step %}

#### Add the price filter

Go to **Filters** and add a new filter. Enter the path manually:

`_product_siteAware.{siteAware}.currencyAware.{currencyAware}.countryAware.{countryAware}.price.effectiveAmount`

{% hint style="info" %}
Choose **Return object** to include the entire price object in the facet response, or **Return value** to return only the price value.
{% endhint %}

<figure><img src="/files/epPpax0a6FIZP5hEQYFQ" alt="BatteryIncluded Filter configuration with price effectiveAmount path and return value setting"><figcaption><p>BatteryIncluded Filter configuration with price effectiveAmount path and return value setting</p></figcaption></figure>
{% endstep %}

{% step %}

#### Optional — Dynamic attributes and mixins

You can also add field templates for dynamic variant attributes and mixin filtering. Configure the corresponding filters under `_product_i18n` for dynamic attributes.

<figure><img src="/files/v2M8YODbi7xhsypPKc5d" alt="Dynamic attribute and mixin filtering field templates"><figcaption><p>Dynamic attribute and mixin filtering field templates</p></figcaption></figure>
{% endstep %}
{% endstepper %}

## B2B Commerce Frontend

When BatteryIncluded is configured as your search provider, the B2B Commerce Frontend uses the same index and search settings when users browse products and run search queries. Variables, searchable fields, synonyms, facets, and related BatteryIncluded configuration are reflected in the storefront search experience.

The example below shows how a synonym configured in BatteryIncluded affects search results on the B2B Commerce Frontend.

{% stepper %}
{% step %}

#### Configure a synonym in BatteryIncluded

In the BatteryIncluded portal, go to **Dictionary** and add a multi-way synonym cluster. For example, map `wireless` to `cordless` so both terms match the same products.

<figure><img src="/files/T5LKOxcVl7IykLYCpDIo" alt="BatteryIncluded Dictionary synonym cluster mapping wireless to cordless"><figcaption><p>BatteryIncluded Dictionary synonym cluster mapping wireless to cordless</p></figcaption></figure>
{% endstep %}

{% step %}

#### Verify search on the B2B Commerce Frontend

On the B2B Commerce Frontend, search for a term from the synonym cluster — for example `wireless saw`. Products that use the related term in their indexed data (such as `cordless`) are returned in the results.

<figure><img src="/files/exRTkD8hLqYR1uiF22gG" alt="B2B Commerce Frontend search results for wireless saw showing cordless products"><figcaption><p>B2B Commerce Frontend search results for wireless saw showing cordless products</p></figcaption></figure>
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.emporix.io/ce/system-management/search/batteryincluded.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.