> For the complete documentation index, see [llms.txt](https://developer.vario-software.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.vario-software.de/cookbook/onlineshops-and-marketplaces-app/integrations.md).

# 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)`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.vario-software.de/cookbook/onlineshops-and-marketplaces-app/integrations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.