Ctrlk
CommunitySupport PortalYouTubeFree trialSign Up!
For the complete documentation index, see llms.txt. This page is also available as Markdown.

BatteryIncluded Search Provider

Configure BatteryIncluded as search provider with webhooks, indexing, and portal setup.

Contact the Emporix Support Team to set up your Emporix tenant in BatteryIncluded before proceeding.

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.

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

After products are indexed into BatteryIncluded, continue with 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 and make sure you have the following in place:

  • Enabled webhook service

  • Enabled index-item.updated and index-item.deleted events

  • Configured Svix access

Use the steps below only if you chose the webhook-based path. For most tenants, use the native Indexing Service instead.

Creating and updating products

1

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

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.

Svix endpoint configuration for BatteryIncluded create and update
Svix endpoint configuration for BatteryIncluded create and update
2

Save the endpoint

Choose Create and check if your configuration was properly saved.

3

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.

4

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.

Deleting products

1

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

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.

Svix endpoint configuration for BatteryIncluded delete
Svix endpoint configuration for BatteryIncluded delete
2

Save the endpoint

Choose Create and check if your configuration was properly saved.

3

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

4

Enable transformations

In the Transformations section, set the transformation feature to enabled.

5

Configure the transformation mapping

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

  /**
* @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
}
6

Save your changes

If the output is correct, save your changes.

7

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.

Indexing Service configuration

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

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 for details.

Enabling BatteryIncluded

To register BatteryIncluded as your indexing provider, send a Create a new configuration request with your credentials, or use Update configuration by provider name to update an existing configuration.

To update an existing configuration:

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

BatteryIncluded public integration key under API Connection BI-Webshop
BatteryIncluded public integration key (`searchKey`)
BatteryIncluded server API key under API Connection Data-BI
BatteryIncluded server API key (`writeKey`)

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 for background on SPLIT vs MERGE.

To create the configuration, call the Creating configurations endpoint.

To update an existing configuration, call the Updating a configuration endpoint.

Propagating index strategy changes may take up to 1 hour. See Changing index strategy.

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

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.

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.

Providing both excludedMixinKeys and includedMixinPaths in the same request is rejected with a 400 Bad Request error.

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.

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:

To index all site-aware subtrees and nothing else:

*_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:

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

After changing mixin filtering settings, trigger a full reindex so that existing products are re-processed with the new configuration.

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").

See the _product fields (language-neutral attributes)
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.

See the _product_i18n entry fields (one entry per language)
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.

See the _product_siteAware entry fields (one entry per site)
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>

Currency-level pricing keyed by ISO 4217 currency code (e.g. "USD", "EUR"). Each entry contains a countryAware map keyed by ISO 3166-1 alpha-2 country code. Each country entry holds: • prices — the full list of all prices for that country. Each price object contains priceId, currency, originalAmount, effectiveAmount, validFrom, validTo, and priceModel (see below). • price — a single price object selected for facet search and sorting: the price with the lowest effectiveAmount across all prices for that country. Omitted when no price carries an effectiveAmount. Has the same shape as a prices entry.

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.

See a full BatteryIncluded example document

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.

Category

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

1

Enable the filterable setting

In the BatteryIncluded portal, go to Schema → Import, open _product_i18n → {locale} → categoryBreadcrumbs → displayPath, and switch on Filterable.

Filterable setting for category breadcrumbs in BatteryIncluded schema
Filterable setting for category breadcrumbs in BatteryIncluded schema

Enable the Filterable setting for every language separately in your schema structure.

2

Enable filterable categoryIds

In the BatteryIncluded portal, go to Schema → Import, open _product → categoryIds, and switch on Filterable.

Filterable setting for categoryIds in BatteryIncluded schema
Filterable setting for categoryIds in BatteryIncluded schema
3

Add the category filter

Go to Filters and add a filter for _product_i18n.{locale}.categoryBreadcrumbs.displayPath. Choose Select (Tree) and Return object.

BatteryIncluded Filter configuration with brand, category breadcrumbs, and price effectiveAmount paths
BatteryIncluded Filter configuration with brand, category breadcrumbs, and price effectiveAmount paths
4

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.

Explore setup icon in BatteryIncluded
Explore setup icon in BatteryIncluded
5

Map image and category fields

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

  • Image – _product.media.0.url

  • Category – _product_i18n.categoryBreadcrumbs.displayPath

Explore More settings for image and category fields
Explore More settings for image and category fields

Brand

To use brand name as a facet, mark the field as filterable in the BatteryIncluded schema and configure the filter.

1

Enable the filterable setting

In the BatteryIncluded portal, go to Schema → Import, open _product_i18n → {locale} → brand → name, and switch on Filterable.

Filterable setting for brand name in BatteryIncluded schema
Filterable setting for brand name in BatteryIncluded schema

Enable the Filterable setting for every language separately in your schema structure.

2

Set the brand name label

In the same field configuration, set the field label to Brand Name. This label is required for brand to display correctly on the B2B Commerce Frontend.

Brand Name label set for brand name in BatteryIncluded schema
Brand Name label set for brand name in BatteryIncluded schema
3

Add the brand filter

Go to Filters and add a filter for _product_i18n.{locale}.brand.name. Choose Select (Default) and Return value.

BatteryIncluded Filter configuration with brand, category breadcrumbs, and price effectiveAmount paths
BatteryIncluded Filter configuration with brand, category breadcrumbs, and price effectiveAmount paths

Price

The steps below show how to add a price range filter.

1

Make price filterable

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

Filterable float setting for effectiveAmount price field
Filterable float setting for effectiveAmount price field
2

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

Choose Return object to include the entire price object in the facet response, or Return value to return only the price value.

BatteryIncluded Filter configuration with brand, category breadcrumbs, and price effectiveAmount paths
BatteryIncluded Filter configuration with brand, category breadcrumbs, and price effectiveAmount paths

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.

1

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:

  • locale under _product_i18n

  • siteAware under _product_siteAware

  • currencyAware under _product_siteAware.{siteAware}.currencyAware

  • countryAware under _product_siteAware.{siteAware}.currencyAware.{currencyAware}.countryAware

BatteryIncluded schema variables for locale, siteAware, currencyAware, and countryAware
BatteryIncluded schema variables for locale, siteAware, currencyAware, and countryAware
2

Save your changes

Choose Save. Product data returned by search is filtered according to the active variable values.

3

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.

  • _product_i18n → {locale} → mixins → highlights → highlights

  • _product_i18n → {locale} → brand → name

  • _product_i18n → {locale} → categoryBreadcrumbs → displayPath

  • _product_siteAware → {siteAware} → currencyAware → {currencyAware} → countryAware → {countryAware} → price → effectiveAmount

BatteryIncluded Schema Browse query filters and Try it panel
BatteryIncluded Schema Browse query filters and Try it panel

The examples below show how the same product document is shaped with and without 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.

See an example document with variables

Without variables, the full indexed document is returned, including all locales under _product_i18n and all sites under _product_siteAware.

See an example document without variables

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

1

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. For example:

  • _product → id

  • _product → code

  • _product_i18n → {locale} → name

  • _product_i18n → {locale} → description

  • _product_i18n → {locale} → categoryBreadcrumbs → displayPath

BatteryIncluded Relevance Search tab with searchable fields, priority, and typo settings
BatteryIncluded Relevance Search tab with searchable fields, priority, and typo settings
2

Save your changes

Choose Save to apply the searchable field configuration.

Variants

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

1

Enable the filterable setting

In the BatteryIncluded portal, go to Schema → Import, open _product → parentVariantId, and switch on Filterable.

Filterable setting for parentVariantId in BatteryIncluded schema
Filterable setting for parentVariantId in BatteryIncluded schema
2

Configure variant grouping

In the BatteryIncluded portal, go to Relevance → Variants and set up grouping by the relevant attribute:

  • _product → parentVariantId

BatteryIncluded variants setup under Relevance
BatteryIncluded variants setup under Relevance
3

Check variants in Explore

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

Product variants shown in BatteryIncluded Explore Search
Product variants shown in BatteryIncluded Explore Search

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.

BatteryIncluded requires at least one synonym entry before Explore works. Add synonyms in Dictionary → Synonyms.

BatteryIncluded synonym dictionary
BatteryIncluded synonym dictionary

Dynamic filtering

As an optional configuration, you can also add field templates for dynamic variant attributes and mixin filtering so shoppers can filter search results by those values.

1

Add dynamic field templates

In Schema → Import, choose + ADD FIELD and enter the path for the dynamic attribute or mixin field you want to filter on (for example _product_i18n.{locale}.dynamicVariantAttributesValues.<attributeKey>).

Adding a dynamic field template in BatteryIncluded schema import
Adding a dynamic field template in BatteryIncluded schema import

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.

1

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.

BatteryIncluded Dictionary synonym cluster mapping wireless to cordless
BatteryIncluded Dictionary synonym cluster mapping wireless to cordless
2

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.

B2B Commerce Frontend search results for wireless saw showing cordless products
B2B Commerce Frontend search results for wireless saw showing cordless products
PreviousAlgolia Search ProviderNextOptimistic Locking

Last updated

Was this helpful?