---
title: "Academy App"
canonical_url: "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations"
locale: en
meta:
  "og:title": "Academy App"
---

[Go to home](https://academy.laioutr.com/en)

- [Apps](https://academy.laioutr.com/en/bereiche/apps)

- [Search and recommendations](https://academy.laioutr.com/en/leitfaeden/search-and-recommendations)

- [Battery Included: connect search and recommendations](https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations)

# Battery Included: connect search and recommendations

The Battery Included app brings full-text search, search suggestions and product recommendations from a BatteryIncluded collection into the storefront. It needs the collection ID, an API key and a commerce app such as Shopify for product data.

## Before you start

<dl>

<dt>Plan</dt>
<dd>Laioutr Commerce (Growth or higher) and a BatteryIncluded account</dd>

<dt>Role</dt>
<dd>Developer role on the environment to save settings in Configuration</dd>

<dt>Duration</dt>
<dd>8 min</dd></dl>

### Prerequisites

- BatteryIncluded collection that indexes the catalogue
- API key for that collection
- Installed and configured commerce app, for example Shopify
- Product IDs in BatteryIncluded match the IDs of the commerce app

Last reviewed on October 15, 2026

Provides full-text search with filters and sorting, suggestions while typing and product recommendations from BatteryIncluded. Orchestr loads the product data for the hits from the commerce app.

[Developer documentation](https://docs.laioutr.com/apps/app-docs/battery-included)

## How it works

1. Create a collection and index the catalogueWhere: BatteryIncluded dashboard · Role: E-commerce team or developer · Duration: 30 min
2. Copy collection ID and API keyWhere: BatteryIncluded dashboard · Role: Developer · Duration: 2 min
3. Install the appWhere: Cockpit, Apps · Role: Developer · Duration: 2 min
4. Enter collection and apiKey, test the connection, saveWhere: Cockpit, Configuration · Role: Developer · Duration: 5 min
5. Start a deploymentWhere: Cockpit, Deployments · Role: Developer · Duration: 5 min
6. Check search, suggestions and recommendationsWhere: Studio and storefront · Role: Content manager · Duration: 10 min

## Configuration

| Field | Purpose | Where to find it | Required | Per environment |
| --- | --- | --- | --- | --- |
| `baseURL` | Address of the BatteryIncluded API. | Default https://api.batteryincluded.io; change only for a different address. | No | Yes |
| `collection` | Identifier of the collection that holds the catalogue. It is part of every API path. | BatteryIncluded dashboard, collection settings | Yes | Yes |
| `apiKey` | API key for authenticating with BatteryIncluded. Used only on the server and stored encrypted. | BatteryIncluded dashboard, collection credentials | Yes | Yes |

## Common errors

<dl>

<dt>Search returns no hits.</dt>
<dd>**Cause:** The collection ID is wrong, the collection is empty or the API key has no access.</dd>
<dd>**Fix:** Check collection and apiKey in Configuration, run Test connection and check indexing in BatteryIncluded.</dd>

<dt>Hits or recommendations appear without image, name or price.</dt>
<dd>**Cause:** The product IDs in BatteryIncluded do not match the IDs of the commerce app.</dd>
<dd>**Fix:** Switch the IDs in the collection to the format of the commerce app and re-index.</dd>

<dt>Changed settings have no effect.</dt>
<dd>**Cause:** The values are saved but not yet deployed.</dd>
<dd>**Fix:** Start a new deployment under Deployments.</dd>

<dt>Results appear in the wrong language.</dt>
<dd>**Cause:** The collection does not contain the storefront language.</dd>
<dd>**Fix:** Add the missing language in BatteryIncluded and re-index.</dd></dl>

**Battery Included** is a search and recommendations app. The package `@laioutr-app/battery-included` connects the storefront to the BatteryIncluded API and provides three functions: full-text search with filters, sorting and pagination, suggestions while typing, and product recommendations such as "similar products" or "frequently bought together".

BatteryIncluded indexes the catalogue, while the product data itself still comes from the commerce app, for example Shopify. The app returns hits and recommendations as product IDs, and Orchestr loads the full product data from the commerce backend. The IDs in BatteryIncluded therefore have to match those of the commerce app.

Battery Included does not provide cart, navigation or categories. Suggestions run after other sources, so they can be combined with suggestions from other apps. The app sets no cookies. The language of each request follows the storefront language, so the collection has to contain these languages.

## Step by step

1. 1 ### Step 1: Prepare the collection

   In the BatteryIncluded account, create a collection that indexes the catalogue of the commerce app. Note the collection ID and the API key.
2. 2 ### Step 2: Install the app

   Open **Apps** in the project, find Battery Included in the **Search** tab and select **Install**.
3. 3 ### Step 3: Enter the credentials

   Open **Configuration** in the environment menu and select Battery Included. Enter `collection` and `apiKey`; change `baseURL` only for a different API address.
4. 4 ### Step 4: Test and save

   Use **Test connection** to check the values, then select **Save settings**.
5. 5 ### Step 5: Start a deployment

   Start a new deployment with **Deploy** under **Deployments**. Saved settings only take effect with the next deployment.
6. 6 ### Step 6: Check search and recommendations in Studio

   Open the search results page and a product page in Studio. Hits, suggestions and recommendations appear in the preview with real product data.

## Check the result

Enter a search term on the storefront: suggestions appear while typing, and the results page shows hits with filters and sorting. A product page shows recommendations with image, name and price from the commerce app.

## Frequently asked questions

Does Battery Included replace the commerce app?

No. Battery Included only provides search, suggestions and recommendations. Product data, cart and categories still come from the commerce app.

Why do hits appear without product data?

The product IDs in the collection do not match the IDs of the commerce app. Align the IDs in BatteryIncluded with the format of the commerce app, for example the Shopify ID or the SKU.

Is the API key visible in the browser?

No. The API key is only used on the server. Cockpit stores it encrypted and afterwards shows only the last four characters.

Does Battery Included need an entry in the consent banner?

The app itself sets no cookies, and all requests run without a visitor identifier. The privacy team checks how to describe it in the privacy policy.

## Related

- [Find, install and configure apps](https://academy.laioutr.com/en/artikel/find-install-and-configure-apps)6 min

  Apps are listed in the Cockpit catalogue under Apps, installed per environment and set up under Configuration. The storefront uses them from the next deployment onwards.
- [Enter credentials and test the connection](https://academy.laioutr.com/en/artikel/enter-credentials-and-test-the-connection)5 min

  App credentials are entered per environment under Configuration, checked with Test connection and stored with Save settings. They take effect with the next deployment.
- [Set up search and the search results page](https://academy.laioutr.com/en/artikel/set-up-search-and-the-search-results-page)6 min

  Search consists of the search field with suggestions in the shop header and the search results page with search term, result count, filters and product grid. Suggestions and results come from the search or commerce app through Orchestr, so search quality depends on the connected search service.
- [Connect Shopify](https://academy.laioutr.com/en/apps/connect-shopify)10 min

  The Shopify app connects a Shopify store to Laioutr through the Storefront API, Customer Account API and Admin API. Products, collections, cart, menus, content and customer login come straight from Shopify.
- [Nimstrata: AI search and recommendations via Google Retail API](https://academy.laioutr.com/en/apps/nimstrata-ai-search-and-recommendations-google-retail)10 min

  The Nimstrata app connects the storefront to the Google Retail API through Retail Connect: AI-powered search, category listings, search suggestions, recommendations and event tracking. It requires a Nimstrata project with a catalogue and the Shopify app in the same project.

## [Search and recommendations](https://academy.laioutr.com/en/leitfaeden/search-and-recommendations)

Search this guide

1. [Battery Included: connect search and recommendations](https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations)8 min
2. [Nimstrata: AI search and recommendations via Google Retail API](https://academy.laioutr.com/en/apps/nimstrata-ai-search-and-recommendations-google-retail)10 min

## Structured Data

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@id": "https://academy.laioutr.com/#website",
      "@type": "WebSite",
      "inLanguage": "en",
      "name": "Default",
      "url": "https://academy.laioutr.com/",
      "translationOfWork": {
        "@id": "https://academy.laioutr.com/#website"
      }
    },
    {
      "@id": "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations#webpage",
      "name": "Academy App",
      "url": "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations",
      "@type": [
        "WebPage",
        "FAQPage"
      ],
      "breadcrumb": {
        "@id": "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations#breadcrumb"
      },
      "isPartOf": {
        "@id": "https://academy.laioutr.com/#website"
      },
      "mainEntity": [
        {
          "@id": "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations#/schema/question/1"
        },
        {
          "@id": "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations#/schema/question/2"
        },
        {
          "@id": "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations#/schema/question/3"
        },
        {
          "@id": "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations#/schema/question/4"
        }
      ],
      "potentialAction": [
        {
          "@type": "ReadAction",
          "target": [
            "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations"
          ]
        }
      ]
    },
    {
      "@id": "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations#breadcrumb",
      "@type": "BreadcrumbList",
      "itemListElement": [
        {
          "@type": "ListItem",
          "name": "Home",
          "item": "https://academy.laioutr.com/en",
          "position": 1
        },
        {
          "@type": "ListItem",
          "name": "Apps",
          "item": "https://academy.laioutr.com/en/bereiche/apps",
          "position": 2
        },
        {
          "@type": "ListItem",
          "name": "Search and recommendations",
          "item": "https://academy.laioutr.com/en/leitfaeden/search-and-recommendations",
          "position": 3
        },
        {
          "@type": "ListItem",
          "name": "Battery Included: connect search and recommendations",
          "item": "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations",
          "position": 4
        }
      ]
    },
    {
      "@id": "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations#/schema/question/1",
      "@type": "Question",
      "inLanguage": "en",
      "name": "Does Battery Included replace the commerce app?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "<p>No. Battery Included only provides search, suggestions and recommendations. Product data, cart and categories still come from the commerce app.</p>"
      }
    },
    {
      "@id": "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations#/schema/question/2",
      "@type": "Question",
      "inLanguage": "en",
      "name": "Why do hits appear without product data?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "<p>The product IDs in the collection do not match the IDs of the commerce app. Align the IDs in BatteryIncluded with the format of the commerce app, for example the Shopify ID or the SKU.</p>"
      }
    },
    {
      "@id": "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations#/schema/question/3",
      "@type": "Question",
      "inLanguage": "en",
      "name": "Is the API key visible in the browser?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "<p>No. The API key is only used on the server. Cockpit stores it encrypted and afterwards shows only the last four characters.</p>"
      }
    },
    {
      "@id": "https://academy.laioutr.com/en/apps/battery-included-search-and-recommendations#/schema/question/4",
      "@type": "Question",
      "inLanguage": "en",
      "name": "Does Battery Included need an entry in the consent banner?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "<p>The app itself sets no cookies, and all requests run without a visitor identifier. The privacy team checks how to describe it in the privacy policy.</p>"
      }
    }
  ]
}
```