Shopware Installation Guide

updated 2 days ago

In this guide, you can read and learn about how to install the plugin for Shopware.

Note that the current version of the plugin only supports v. 6 of Shopware up to 6.6.
The repository for previous versions and current version are available here: https://packagist.org/packages/helret/hello-retail

Hello Retail is easily integrated with Shopware, as Shopware provides a plugin that can be installed directly on the platform. Please follow this guide, and you will be up and running in no time.

Note: The plugin automatically installs the JavaScript snippet that does view & click tracking, as well as conversion & cart tracking.

Important:
When upgrading to the last Shopware plugin, we had added additional security through a token system. This means that you will need to send the token to support@helloretail.com for the feeds to work after the update.

Install the Plugin

The plugin should be installed using composer:

composer require helret/hello-retail:4.4.1

For Shopware version ^6.6, use plugin version 5.2.1
For Shopware version ^6.5, use plugin version 4.4.1

If you're unsure which version to use, check the GitHub repository.
You can find the required Shopware version in the composer.json file.

Configuration

Once the plugin has been required using composer, installed and activated using bin/console, it's time to add the new Sales Channel.

Start by logging into your Shopware Admin account.
On the dashboard view, navigate to the left-hand side menu. Navigate to Settings and then Plugins.
From here, then at the section of the Sales Channel and then click on the plus icon to add a new Sales Channel.
Give the channel:

a name such as Hello Retail
select the storefront
select the storefront domain

5. Activate it and click Save.

6. After the previous step has been saved, the page reloads, and you can now see the Orders and Products feed URLs.

Copy and paste these 3 URLs, and the Authorization token and send them to support@helloretail.com along with the shop domain, and don't forget to save the Sales Channel.

Click "Force generation" to create the initial XML files needed for setting up Hello Retail.

To confirm the files have been generated, go to the appropriate server and run the following command:

find . -type f -name "products.xml"

Initialize the Plugin

Start by logging into your Shopware Admin account.
On the dashboard view, navigate to the left-hand side menu. Navigate to Extensions and then My Extensions.
Click on Hello Retail plugin and the three dots, and choose Configure.
When the installation asks for the Hello Retail partnerID, you should simply input "0".
The partnerID was previously required by Hello Retail to evaluate which setup the script should invoke. This is no longer the case, but the module for Shopware requires that the field is not empty.
Sync Advanced pricing and limit orders
We suggest that you don't limit the orders for the first run. The more order data you can supply Hello Retail, the better your algorithms will work, as well you will have more data to analyze in your Audience solution.

After the first initial run, you can save server power by limiting the orders so they only go one month back.

You can read more about advanced pricing in Shopware here.
The "Include product data in category feed" should, by default, be off and should only, in rare cases, be enabled. This option adds additional strain on your servers when we load the category feeds.
For each feed (Orders, Products & Categories), select the frequency you want the feeds to be updated with.
Be aware that the faster you want us to pull data, the more strain it will have on your servers. We suggest that you have the most frequent product updates and then less frequently load the order feed and category feed.

Setting Up Data Feeds

Before you begin, make sure you have your login credentials for the Hello Retail dashboard:
https://my.helloretail.com/

Log in to the Hello Retail dashboard.
Select the webshop you want to configure.
In the left-hand menu, go to Configuration → Data Setup → Feeds.
Click Feeds, then click Add New to create a new product feed.
Select XML as the feed type.
Enter the product feed URL for the webshop you're setting up. To find it, go to your Shopware instance, navigate to the Sales Channel, click Hello Retail, and then click Copy next to the Products URL.
Once the URL is entered, additional fields will appear.
Click Add header and fill in the following:
- Header: Authorization
- Value: Bearer tok_sw_XXXXX
  
  The token above is just an example. Be sure to use the actual token you can find in the Hello Retail Sales channel.
For content and order feeds, please send both URLs to support@helloretail.com, and we’ll assist you with the setup.

Settings of the Product Feed

Once you've added the necessary Authorization token, you’ll need to adjust the feed permissions.

Go to the Settings tab in the feed configurator.
Enable the options to create and delete products.

Note: This only affects data inside Hello Retail and will not impact your Shopware webshop.

Transformation & Feed Testing

After updating the settings, you can test the connection between Hello Retail and Shopware:

Navigate to the Transform tab.

Add the following code snippet:

function transform(product:any): TransformationResult {
    // remove products that have a falsy displayGroup value.
    if(!product.extraData?.displayGroup) return;
    return {
        ...product,
        extraData: {
            ...(product.extraData || {}),
            wexoDisplayGroupGroupingKey: product.extraData.displayGroup
        }
    };
}

Want to learn more about how transformations work? Check out the transformation guide.

Save the configuration.
Click Test feed (with 2 filters).

Before running the test:

Ensure the Data path to products is correctly set.
Typically, the correct path is:
root > products > product
This should match the structure of your generated XML file.
Don’t forget to Save the feed before testing.

Troubleshooting Tips

If you run into issues, try accessing the feed using Postman or a similar tool with the same Authorization token.
Check if Hello Retail’s IP address has been whitelisted on the server. If not, contact your system administrator to confirm access.

Important Notes

Products without an imgUrl (i.e., missing or empty image URL) will not appear in search results.
You can add a placeholder image through either:
- A transformation rule in the Hello Retail dashboard
- Or by including it directly in the product feed
Make sure to set up a cronjob to automatically export or generate the feed at regular intervals.

Setup of Product Recommendations

You can set up recommendations in two ways:

By integrating directly with our API
Or by using our managed templates

Not sure which option is right for you? Reach out to us at support@helloretail.com – we’re happy to help.

If you are using the managed templates you have the option to drag 'n drop the recommendation boxes as shown below.

Gif - Shopware
You can read here on how to get the product box key ID. Paste this copied key into the Recommendation ID field.

Setup of Personalized Search

You can implement Hello Retail Search in three ways:

Integrated Search
Managed Templates
Direct API integration

Integrated Search is the fastest way to get started. With just a few adjustments, you can power your existing design using Hello Retail’s API. It’s a quick setup with minimal effort - but keep in mind that it doesn’t support Redirects or Retail Media (including Banners).

Managed Templates offer a selection of prebuilt designs that you can easily customize to fit your site. Read more.

API integration gives you full flexibility and control over the search experience. Read more.

Not sure which option fits your needs? Reach out to us at support@helloretail.com – we’re happy to help.

Integrated Search

Configuring the Hello Retail Search in Shopware

To access the configuration, go to the Shopware backend and navigate to:

Extensions > My Extensions > Search for "Hello Retail" > Click the three dots > Select "Configure"

Scroll down to the "Search" section to find the following settings:

Enabled
Toggle this to enable or disable the Hello Retail’s search functionality (Integrated Search). When enabled, Hello Retail will take over the search via its API. Disable this feature if you use the API or Managed Templates.
Search Config Key
You can find this in the Hello Retail Dashboard under Search > Overview.
The key works for all three search types, but it's most commonly used with the "Overlay" type.
Open the search to locate the config key you need.
Replace search page results
If enabled, the default Shopware search results page will be replaced with data from Hello Retail.
Amount of search results (Category/Content)
Set the number of category or content results Hello Retail should return.
Replace suggest results
If enabled, the default Shopware live search (suggestions) will be replaced by Hello Retail data.
Amount of suggestions (Product)
Define how many product suggestions should appear in the live search.
If left blank or set to 0, the default is 10.
Amount of suggestions (Category/Content)
Set how many category or content suggestions Hello Retail should return.

Sorting and Filters

Sorting and filters on the search results page in the frontend are also provided by Hello Retail.
You can configure them via the Hello Retail Dashboard:

Search > Overview > Click on the relevant search configuration > Scroll down to "Filters and Sorting".

Note: The order in which filters are shown on the frontend is not controlled by Hello Retail. This is managed in the Shopware backend under:
Catalog > Properties

When you create new property groups in Shopware, they are automatically transferred to Hello Retail through the product feed - once at least one product includes the new property.

Indexing and Grouping Configuration for Product Data

To ensure correct filtering and proper product listing behavior, you need to update the indexing and grouping settings in the Hello Retail Dashboard.

Go to:
Configuration > Data Setup > Data Fields (select the Product Fields tab)

Fields that must be marked as Indexed:

extraData.manufacturerId
extraData.isCloseoutAvailable
- Required to support the hideProductsOutOfStock feature (a.k.a. ProductCloseoutFilter)
All fields starting with extraDataList.propertyGroup_
- These handle product filtering via Shopware’s property groups

Grouping Configuration

Under Product Group, ensure that only the correct grouping key is used:

Only mark extraData.displayGroup or wexoDisplayGroupGroupingKey (depending on your implementation) as the grouping key.
- This is essential for proper handling of product grouping and presentation in the Shopware storefront.

Important:

Products must be grouped by extraData.displayGroup (or wexoDisplayGroupGroupingKey, if added via transformation).

If you are modifying or adding extraData using a transform, remember to extend or copy the existing object—not overwrite it.

Remove products without a valid displayGroup (this is typically handled in line 3 of the transformation).

Search Engine Settings

To ensure the search behaves correctly:

Go to:
Search > Search Engines > [Product search engine] > Search Settings

Update the Show Variants setting to:
“Show only the first variant of a product”

This prevents duplicate listings and ensures a clean search result display.

Category Setup

To enable category functionality, you must first contact Hello Retail Support and request that they map or add the field extraData.id to your feed.

This is a managed feed, so you won't be able to modify it yourself via transformation.

Testing the Setup

To verify the setup, you can enable the Request Log:

Go to API in the Hello Retail Dashboard
Toggle "Request Log" to ON

Reminder:
Don’t forget to turn it off again after testing, as it will otherwise remain active for 7 days.