Integrations

Outbound (ERP → Platform)

Outbound integrations push data from the ERP to the external platform. Each type is triggered by an ERP webhook, queued, and processed during the PROCESS_QUEUES cron. All outbound services follow the same pattern: Fetch via VQL → Transform → Push to platform API.

Topic	Webhook	What syncs	Transfer Toggle
upsert.article	article.update	Article master data (name, description, EAN, weight)	UPLOAD_ARTICLE_MASTERDATA
update.article-price	article-price.update	Net and gross sales prices	UPLOAD_ARTICLE_PRICE
update.article-stock	sales_channel.stockChange	Available stock quantity	UPLOAD_ARTICLE_STOCK
upsert.article-media	article-shelf.update	Product images	UPLOAD_ARTICLE_IMAGE
update.orderStatus	Delivery document created	Shipping confirmation + tracking	UPLOAD_ORDER_STATUS

Fetching Data

Use VQL with article.shopListing as the FROM clause to fetch article data including custom fields. Filter by listings.salesChannel.id to scope to your channel. Access custom EAV fields via listings.custom.<eavGroupKey>.<attributeKey>.

Storing the External ID

After creating a product on the platform, store the returned ID on the article listing using a PATCH request with x-vario-suppress-own-webhooks: true to prevent triggering another webhook.

Tax Mapping

For price sync, platforms often require a tax rate or tax class. Store a mapping between ERP tax types and platform tax IDs in your app, scoped by sales channel.

Inbound (Platform → ERP)

Inbound integrations import data from the external platform into the ERP using the MultiPart Import system. The pattern is: Fetch from platform → Transform → Upload via MultiPart Import.

Order Import

The most common inbound integration. Triggered by the ORDER_IMPORT cron webhook.

1. Read the LAST_ORDER_IMPORT_TIMESTAMP parameter
2. Fetch orders from the platform since that timestamp (supports paginated fetching)
3. Transform to the VARIO import format
4. Upload via MultiPartImporter with the account-order preset
5. Update the timestamp parameter

The AUTO_ORDER_IMPORT parameter controls whether orders are automatically executed or only validated for manual review.

Product Import

Used for marketplace apps where products originate on the platform, not in the ERP. Same pattern as order import with a product preset. After import, store the platform ID on the article listing to enable outbound syncs.

Customer Import

Most apps do not need standalone customer import — customer data is embedded in the order import. Only use standalone import if the platform has a customer registration flow independent of orders. Uses an account preset.

MultiPart Import

The MultiPartImporter wraps the ERP's multi-part import API:

1. Copies an import preset (defines field mappings)
2. Uploads data via pushChunk(fileName, data) — supports pagination
3. Creates import runs and waits for data extraction
4. Validates or executes the import

Import presets are created during the app migration using methods.createMultipartImportPreset(body).