Core Concepts

Sales Channels

Sales channels represent connections to external platforms. Every shop app creates one Sales Channel Backend (represents the integration itself, e.g. "Shopware 6") and one or more Sales Channels (one per connected shop/store). A single app can manage multiple channels — for example, connecting to three different Shopware stores.

Backends and channels are created during the app migration. Register sales_channel.create and sales_channel.delete webhooks to react when channels are added or removed. In the create handler, initialise default parameters and register per-channel webhooks.

Each article in the ERP can have listings — one per sales channel. A listing stores channel-specific data like the external platform ID. Use article.shopListing in VQL queries and filter by listings.salesChannel.id.

Webhooks

Shop apps use two types of webhooks:

ERP Webhooks

Triggered by data changes in the ERP. Each event creates a queue entry for outbound processing.

Event	Trigger	Queue Topic
article(sales-channel-id=<id>).update	Article master data changes	upsert.article
article-price.update	Price changes	update.article-price
sales_channel.stockChange	Stock level changes	update.article-stock
article(sales-channel-id=<id>)-shelf.update	Media changes	upsert.article-media
document.customer_delivery_document.order_to_delivery	Delivery note created	update.orderStatus
sales_channel.create	New channel added	— (initialise config)
sales_channel.delete	Channel removed	— (clean up)

Article and media webhooks use a sales-channel-id filter so only changes relevant to your channel trigger the webhook. Use x-vario-suppress-own-webhooks: true when writing back to the ERP to prevent infinite loops.

Cron Webhooks

Triggered on a schedule. Used for periodic tasks like importing orders or processing the outbound queue.

Webhook	Purpose
ORDER_IMPORT	Fetches new orders from the platform
PROCESS_QUEUES	Processes queued outbound sync entries

Data Flow

Outbound (ERP → Platform)

ERP Webhook → Queue Entry → PROCESS_QUEUES Cron → Fetch via VQL → Transform → Push to Platform

When an ERP webhook fires (e.g. article update), the handler creates a queue entry. The PROCESS_QUEUES cron picks up queued entries, fetches the full data from the ERP via VQL, transforms it to the platform's API format, and pushes it.

Inbound (Platform → ERP)

ORDER_IMPORT Cron → Fetch from Platform → Transform → MultiPart Import → ERP

The cron webhook triggers a fetch of new data from the platform (e.g. orders since the last import timestamp). The data is transformed into the VARIO import format and uploaded via the MultiPart Import API.

Queue

Outbound sync uses a queue to batch, deduplicate, and retry operations. Queue entries are stored within the app itself.

Lifecycle

QUEUED → PROCESSING → COMPLETED
                    → FAILED (retried on next run)

1. ERP webhook fires → handler creates entry with state QUEUED
2. PROCESS_QUEUES cron fires → picks up queued entries in batches
3. Entries move to PROCESSING, attempt count increments
4. On success → COMPLETED. On error → FAILED with error details

To avoid duplicates, check for existing QUEUED or PROCESSING entries before inserting. The batch size is controlled by the QUEUE_BLOCK_SIZE parameter (default: 10).