> For the complete documentation index, see [llms.txt](https://docs.solutioo.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.solutioo.de/shopware/shopware6_en_us/master-data-management/item-matching-and-data-import-from-shopware.md).

# Item Matching & Data Import from Shopware

If you put the Shopware 6 API Connector into operation in a **shop that is already populated**, products, images, properties, and categories usually already exist there. They do **not** have to be created again. Instead, the connector assigns the existing Shopware objects to the matching items in Business Central (“matching") and imports additional data where required. This is the most important step for avoiding duplicates and cleanly marrying the two systems.

This page describes the complete process in detail: from the basic principle through the individual import building blocks (images, attributes, variants, categories) to troubleshooting.

**Why matching is so important**

Every object in Shopware has a unique technical identifier – the **ID**. In Business Central, this identifier is stored on the respective record as a **Web-ID** (for example, `SOUSHW Web ID` on the item). As long as no Web-ID is set, the connector considers the object “not yet linked" and would **create it again** with the next upload. That is exactly what leads to duplicates. Matching ensures that the correct Web-ID is set **before** the first upload runs.

```mermaid
flowchart LR
    S[(Shopware shop with existing data)] -->|Matching| BC[(Business Central item master)]
    BC -->|Web-IDs set| U[Safe update via PATCH]
```

{% hint style="warning" %}
**Mind the order:** Always carry out the matching **before** the first large upload. If you upload first, duplicates may already have been created that are then more time-consuming to clean up (see the section “Cleaning up duplicate Web-IDs").
{% endhint %}

**Step 1 – Assign products by SKU**

The basis is the comparison by **Item No.** The connector searches Shopware for a product whose **`productNumber` (SKU)** exactly matches the Item No. in Business Central, and adopts its Shopware ID as the Web-ID.

{% stepper %}
{% step %}
**Check the numbers**

Make sure that the **Item No. in BC** and the **SKU/productNumber in Shopware** match. Only then can the automatic comparison work.
{% endstep %}

{% step %}
**Start the comparison**

Start the item comparison. The connector calls the Shopware search (`search/product`) with the filter `productNumber = Item No.`.
{% endstep %}

{% step %}
**The Web-ID is set**

If exactly one hit is found, the **Shopware product ID is stored as the Web-ID**. The item then counts as linked; future changes are sent as a **PATCH**.
{% endstep %}
{% endstepper %}

The technical process, including a flow diagram, is described on the page [Product Matching by SKU & Web ID](/shopware/shopware6_en_us/data-from-shopware-download-and-matching/product-matching-by-sku-and-web-id.md).

**Step 2 – Variants and parent items**

If a product in Shopware has **variants** (for example, color/size), the connector can create the **parent item** automatically and link the associated **child items**. The variant axes are mapped as **Option 1, Option 2, and Option 3**. You control which property group represents the color or size axis through the configuration (label and ID of the color/size property). For details, see [Match Variants (Color & Size)](/shopware/shopware6_en_us/data-from-shopware-download-and-matching/match-variants-color-and-size.md).

**Step 3 – Match attributes and properties**

So that filters and properties continue to work in the shop, the **attributes (property groups)** and their **options** should be linked instead of being created twice. The **Match Attributes** action compares existing Shopware attributes with the BC item attributes based on their **name**. If they match, **Web-ID**, **Web attribute**, and **Synchronized** are set – **no new attributes** are created. The associated option values are compared based on their **value**.

You will find detailed instructions, including name and value matching, mapping fields, and pitfalls, under [Match Attributes & Properties (Property Groups)](/shopware/shopware6_en_us/data-from-shopware-download-and-matching/match-attributes-and-properties-property-groups.md).

**Step 4 – What else can be imported?**

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Images &#x26; media</strong></td><td>The cover image and further item pictures are assigned; the cover image is set as the default picture in BC. <a href="/pages/l6ELtsmy3vyYahEyBuPj">Retrieve Product Images &#x26; Media Info</a></td></tr><tr><td><strong>Attributes &#x26; options</strong></td><td>Property groups and their options are linked through a name/value comparison. <a href="/pages/zf9D85c9HHUe89zlKKVs">Match Attributes &#x26; Properties (Property Groups)</a></td></tr><tr><td><strong>Categories &#x26; channels</strong></td><td>Existing categories and sales channels are assigned so that visibility is retained. <a href="/pages/0Qg1uZXkqMaLuz1UbNxx">Download Categories from Shopware</a></td></tr></tbody></table>

**Helper functions**

* **Excel import:** Supports the data import by reading in larger assignment lists in a structured way.
* **Fix Duplicated Web IDs:** If several BC items have accidentally been linked to the same Shopware ID, this function cleans up the duplicates.

**Cleaning up duplicate Web-IDs**

Duplicates typically arise when an upload was run before the matching, or when item numbers were not unique. Proceed as follows:

{% stepper %}
{% step %}
**Narrow down the cause**

In the Activity Log, check which items were transferred as new records instead of as updates.
{% endstep %}

{% step %}
**Run the cleanup**

Use **Fix Duplicated Web IDs** to resolve duplicate links.
{% endstep %}

{% step %}
**Correct the numbers**

Make sure item numbers are unique and consistent, and repeat the comparison for the affected items.
{% endstep %}
{% endstepper %}

**Recommended procedure (best practice)**

1. **Load the initial data** (payment/shipping methods, taxes, channels, customer groups, and so on) – see [Load Shopware Initial Data](/shopware/shopware6_en_us/configuration/load-shopware-initial-data.md).
2. **Download categories and tags** from Shopware so that the assignment is in place.
3. **Match the attributes** so that properties and filters are linked – see [Match Attributes & Properties (Property Groups)](/shopware/shopware6_en_us/data-from-shopware-download-and-matching/match-attributes-and-properties-property-groups.md).
4. **Match products by SKU** and link the variants.
5. **Run a test with a few items**, check the result, and then roll out in waves.

{% hint style="warning" %}
First run the comparison with **a few items** and check the result before you import large volumes.
{% endhint %}

**Troubleshooting**

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Product is created twice</strong></td><td>SKU/productNumber do not match – align the numbers and match the existing product.</td></tr><tr><td><strong>Attribute not linked</strong></td><td>The name differs (capitalization, spaces). Align the names and run the comparison again.</td></tr><tr><td><strong>Variant is missing</strong></td><td>The color/size property is not configured correctly – check the label and ID.</td></tr><tr><td><strong>Image not imported</strong></td><td>Retrieve the media info or set the default picture again.</td></tr></tbody></table>

### Frequently Asked Questions

#### How does the connector distinguish between updating and creating a product?

The decision is made based on the “SOUSHW Web ID”: if it is filled, the existing Shopware product is updated via PATCH. If it is empty, the connector creates the product as a new record (POST) – after a preceding duplicate search via `search/product` on the Item No.

#### Are categories, tags, or attributes that are no longer assigned removed in Shopware?

Yes. During an update, the connector calls `Product_UnAssign_Categories`, `Product_UnAssign_Tags`, and `Product_UnAssign_Properties` and removes assignments that are no longer set in Business Central. This way, the assignment in Shopware exactly matches the current status in BC.


---

# 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://docs.solutioo.de/shopware/shopware6_en_us/master-data-management/item-matching-and-data-import-from-shopware.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.