Shopware Setup Guide

Architecture

Emporiqa uses your store catalog as its knowledge base: the plugin pushes products, variants, prices, stock and landing pages over webhooks as you save them, so there is no separate knowledge base you have to write or keep up to date. For anything your shop pages never covered, you can write a page yourself on the Pages screen in the Emporiqa dashboard: a title and the text in your own words, in up to 10 languages on the same page. You write each language yourself, and any of them can carry a link to the same page on your site. The chat answers from it like it answers from any page your shop sent, and a sync never overwrites it. Up to 25 pages per store. On the Products screen you can set up to 50 products to Promoted or Top: the chat shows them first when they match what the shopper asked, Top before Promoted, and never shows them for unrelated questions. A sync never clears it.

The plugin uses Shopware event subscribers (ProductSubscriber, LandingPageSubscriber, CategorySubscriber, OrderSubscriber) to react to write and delete events. Webhook events are dispatched through Shopware's message queue (Symfony Messenger), so the storefront response completes independently of the outbound HTTP delivery.

Storefront sales channels are auto-detected and mapped to Emporiqa channel keys (slugified from channel names). Headless and API channels are excluded. All translations and currencies for a single product or page consolidate into one webhook event in the format {channel: {language: value}}, matching every other Emporiqa integration.

Transient failures (HTTP 429) are re-queued with a 65-second delay, up to 5 retries. When Emporiqa cannot be reached or answers with a server error, a change is sent again after 1, 5 and 15 minutes and then hourly, six times in all (about 2 hours 20 minutes, from version 1.3.2); a newer save of the same product or page that reaches Emporiqa first is never overwritten by the older one. A change Emporiqa refuses (for example a wrong webhook secret) is not retried: it is logged and kept in Shopware's failed queue. Full syncs split the catalog into configurable batches (default 50, max 200) to keep memory usage bounded.

Requirements

Configuration Reference

All settings live at Extensions → My extensions → Emporiqa → Configuration. Every setting can be overridden per sales channel.

Connection Settings

Sync Settings

Order Tracking Settings (older setup)

These apply only to the older order tracking endpoint. The Order status rule does not use them; see Order status.

Advanced Settings

Most stores don't need to change these.

Dashboard-Managed Settings

These are managed through the Emporiqa admin module UI, not the raw plugin configuration page.

Features

Webhook Payload

Each product (or variant) and page is sent as a single webhook event containing all sales channels, languages, and currencies. Parent products include their variants as separate entries.

Product Event

{
  "identification_number": "product-UUID",
  "sku": "SW-001",
  "channels": ["storefront", "b2b"],
  "names": {
    "storefront": {"en": "Running Shoes", "de": "Laufschuhe"},
    "b2b": {"en": "Running Shoes"}
  },
  "descriptions": {
    "storefront": {"en": "Lightweight running shoes...", "de": "Leichte Laufschuhe..."}
  },
  "links": {
    "storefront": {"en": "https://shop.com/running-shoes", "de": "https://shop.de/laufschuhe"}
  },
  "categories": {
    "storefront": {"en": ["Sports > Footwear > Running"], "de": ["Sport > Schuhe > Laufen"]}
  },
  "brands": {"storefront": "Acme"},
  "prices": {
    "storefront": [
      {"currency": "EUR", "current_price": 89.99, "regular_price": 99.99},
      {"currency": "USD", "current_price": 94.99, "regular_price": 109.99}
    ]
  },
  "availability_statuses": {"storefront": "available"},
  "stock_quantities": {"storefront": 42},
  "images": {"storefront": ["https://shop.com/media/shoes.jpg"]},
  "attributes": {
    "storefront": {"en": {"Color": "Blue", "Size": "42"}, "de": {"Farbe": "Blau", "Größe": "42"}}
  },
  "parent_sku": null,
  "is_parent": true,
  "variation_attributes": {"storefront": {"en": ["Color", "Size"]}},
  "sync_session_id": "shopware-products-abc123"
}

Field Structure

When taxDisplay=both, each price entry also includes price_incl_tax and price_excl_tax. Identifiers use product-<uuid> for parents and variation-<uuid> for variants.

Customization & Events

Every core service is registered behind an interface and can be replaced via Shopware's standard service decoration mechanism. Symfony events are dispatched at key points in the sync lifecycle for lighter-weight extensions.

Service Interfaces

All interfaces live in the Emporiqa\ShopwarePlugin\Service namespace.

Example: decorate the product formatter

<!-- MyPlugin/src/Resources/config/services.xml -->
<service id="MyPlugin\Service\CustomProductFormatter"
         decorates="Emporiqa\ShopwarePlugin\Service\ProductFormatter">
    <argument type="service" id="MyPlugin\Service\CustomProductFormatter.inner"/>
</service>

<?php
declare(strict_types=1);

namespace MyPlugin\Service;

use Emporiqa\ShopwarePlugin\Service\ProductFormatterInterface;
use Shopware\Core\Content\Product\ProductEntity;

class CustomProductFormatter implements ProductFormatterInterface
{
    public function __construct(
        private readonly ProductFormatterInterface $inner,
    ) {}

    public function formatProduct(
        ProductEntity $product,
        array $channelContexts,
        ?string $syncSessionId = null,
    ): array {
        $items = $this->inner->formatProduct($product, $channelContexts, $syncSessionId);

        foreach ($items as &$item) {
            $item['custom_field'] = 'custom_value';
        }

        return $items;
    }

    public function formatProductDelete(string $productId): array
    {
        return $this->inner->formatProductDelete($productId);
    }
}

Extension Events

The plugin dispatches Symfony events at key points in the sync and formatting lifecycle. Listen to these in your own plugin to filter, enrich, or log data without decorating a full service.

All event classes live in the Emporiqa\ShopwarePlugin\Event namespace.

CLI Commands

All sync operations available in the admin dashboard can also be run from the Shopware CLI. Each sync command supports a --dry-run flag that simulates the sync without sending any webhook requests.

bin/console emporiqa:sync:products
bin/console emporiqa:sync:products --dry-run

bin/console emporiqa:sync:pages
bin/console emporiqa:sync:all

bin/console emporiqa:test-connection

Administration API equivalents

Order status

The ready-made Order status rule answers "Where is my order?" in the chat. Emporiqa asks your shop through the plugin's signed order_status endpoint and tells the shopper the status, the order date and, when there is one, the tracking link. It needs plugin version 1.3.0 or newer.

What the shopper sees, what your team gets and how to write your own rules: Rules guide.

Set it up

1. In the Shopware Administration, open Settings → Emporiqa, Settings tab. Once connected, it shows a Ready-made rules card with the Order status address and a Copy button. If the card is not there yet, click Test connection.
2. Click Open in Emporiqa next to Order status. Your Emporiqa dashboard opens at Settings → Rules with Order status highlighted. Click Add.
3. Click Try it and ask about one of your recent orders. When it answers correctly, click Go live.

If you connected with Connect to Emporiqa, there is nothing to copy: Emporiqa fills in your shop's address itself and checks it with your shop. If it ever asks for the address, paste the Order status address the plugin shows, which looks like this:

What the shopper gives

• Signed in to your shop: only the order number. The plugin answers only for that customer's own orders.
• Guest: the order number and the email used for the order.

Endpoint

Older setup: Order Tracking URL

Stores set up before the Order status rule pasted the plugin's Order Tracking URL into their Emporiqa dashboard (Settings → Integration → For your developer → Order tracking API URL). That keeps working as before, controlled by orderTrackingEnabled and orderRequireEmail (see Configuration Reference). Where ready-made rules are offered, the plugin shows it under Advanced as Old order tracking (deprecated). Once Order status is live, clear the URL in your Emporiqa dashboard first, then switch the old order tracking off. The old endpoint:

Signed-in customers

When a shopper is signed in to your store, the chat shows them their own prices and uses their account when it hands the conversation to your team. There is nothing to set up: it starts once the plugin is on the versions below. Guests see your public prices, as before.

• Their own prices, version 1.3.0 or newer: the prices Shopware calculates for that customer, advanced (tier) prices included. The chat asks your store through the signed customer_prices action when it shows a product, and shows the answer to that customer only, on the cards, in quotes and in the product details. Coupons and cart rules apply at your checkout, as before, and a search with a price limit ("under 200") is applied to what the customer pays.
• Their name and email, version 1.3.2 or newer (the Customer info action): the chat greets them by first name, and a handoff reaches your team with the name and email on their account, so they are not asked for them.

Both answer only for the customer the plugin signed in for this store, and only on that customer's own messages: a shopper who signs out is a guest from their next message. Per customer, prices are kept for 5 minutes and the account details for 30. Each customer is limited to 30 requests and each store to 600 every 10 minutes.

Customer info action

From version 1.3.2 the plugin answers a signed customer_info request about a shopper who is signed in to your shop: the name and email of their customer account and their 10 newest orders in the sales channels you sync (order number, date, status, total and currency). Only the account's own orders are listed, never a guest order placed with the same email, an address, a phone number, a customer group or an internal id. With it, a signed-in shopper who asks "where is my order?" without a number gets their newest order, as long as the Order status rule is on; there is nothing to set up.

Requests are signed like Order status and limited to 30 per customer and 600 per store every 10 minutes. To remove a field or add your own under extra, listen to CustomerInfoResponseEvent, which runs after the answer is built; getCustomer() and getOrders() give the loaded entities.

public function onCustomerInfo(CustomerInfoResponseEvent $event): void
{
    $data = $event->getData();
    unset($data['customer']['email']);
    $data['extra'] = ['loyalty_tier' => 'Gold'];
    $event->setData($data);
}

Troubleshooting