Shopware Setup Guide

Architecture

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 is never blocked on outbound HTTP.

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. Other failures fall back to Shopware's standard message queue retry mechanism. 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

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 Tracking

Emporiqa can look up order status on behalf of customers during chat conversations. The plugin exposes a signed inbound endpoint that the Emporiqa backend calls when a customer asks about their order.

Flow

1. Customer asks "Where is my order #10001?" in the chat.
2. Emporiqa sends an HMAC-SHA256 signed POST to your store with the order identifier and timestamp.
3. The plugin verifies the signature, looks up the order, optionally checks the customer email, and returns the order status, totals, addresses, and items.
4. The salesperson presents the order information to the customer.

Endpoint

Setup

The endpoint is active whenever orderTrackingEnabled is true. To enable order lookup from chat, copy the endpoint URL from the Emporiqa admin module and paste it into your Emporiqa dashboard at Settings → Store Integration → Order Tracking:

Troubleshooting