BatteryIncluded Search Provider
Configure BatteryIncluded for production with the native Indexing Service or test direct event forwarding with webhooks.
For production, use the native Indexing Service integration for BatteryIncluded. Direct webhook processing is intended for testing:
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.
Webhook-based (testing) – Test direct forwarding of
index-item.updatedandindex-item.deletedevents to BatteryIncluded through Svix endpoints. See Webhook-based search configuration.
After products are indexed into BatteryIncluded, continue with BatteryIncluded search configurations to set up variables, searchable fields, synonyms, facets, and related search behavior.
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.
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.
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.name>",
"indexName": "<customer.name>",
"writeKey": "<server api key>",
"provider": "BATTERY_INCLUDED"
}'To update an existing configuration:
searchKey— Public integration key from your BatteryIncluded account under API Connection → BI-Webshop.applicationId— Name of your BatteryIncluded account, for examplecustomer.featuredemo.indexName— You can use the same value as forapplicationId.writeKey— Server API Key from your BatteryIncluded account under API Connection → Data-BI.provider— Set toBATTERY_INCLUDED.
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.
After the MERGE strategy is in place, trigger a full reindex to push existing product data to BatteryIncluded in the MERGE document format:
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.
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):
*
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).
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:
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 IETF 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").
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.
Brand
To use brand name as a facet, mark the field as filterable in the BatteryIncluded schema and configure the filter.
Price
The steps below show how to add a price range filter.
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.
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:
localeunder_product_i18nsiteAwareunder_product_siteAwarecurrencyAwareunder_product_siteAware.{siteAware}.currencyAwarecountryAwareunder_product_siteAware.{siteAware}.currencyAware.{currencyAware}.countryAware
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
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.
Without variables, the full indexed document is returned, including all locales under _product_i18n and all sites under _product_siteAware.
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).
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
Variants
You can group related products by shared attributes so shoppers can switch between variants in search results.
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.
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.
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.
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.
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.updatedandindex-item.deletedevents
Creating and updating products
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/importDescription -
BatteryIncluded Create/UpdateMessage filtering - select only the
index-item.updatedevent
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
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/deleteDescription -
BatteryIncluded DeleteMessage filtering - select only the
index-item.deletedevent
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.
Last updated
Was this helpful?