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.
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").
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.
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.
Start the comparison
Start the item comparison. The connector calls the Shopware search (search/product) with the filter productNumber = Item No..
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.
The technical process, including a flow diagram, is described on the page Product Matching by SKU & Web ID.
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).
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).
Step 4 – What else can be imported?
Images & media
The cover image and further item pictures are assigned; the cover image is set as the default picture in BC. Retrieve Product Images & Media Info
Attributes & options
Property groups and their options are linked through a name/value comparison. Match Attributes & Properties (Property Groups)
Categories & channels
Existing categories and sales channels are assigned so that visibility is retained. Download Categories from Shopware
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:
Narrow down the cause
In the Activity Log, check which items were transferred as new records instead of as updates.
Run the cleanup
Use Fix Duplicated Web IDs to resolve duplicate links.
Correct the numbers
Make sure item numbers are unique and consistent, and repeat the comparison for the affected items.
Recommended procedure (best practice)
Load the initial data (payment/shipping methods, taxes, channels, customer groups, and so on) – see Load Shopware Initial Data.
Download categories and tags from Shopware so that the assignment is in place.
Match the attributes so that properties and filters are linked – see Match Attributes & Properties (Property Groups).
Match products by SKU and link the variants.
Run a test with a few items, check the result, and then roll out in waves.
First run the comparison with a few items and check the result before you import large volumes.
Troubleshooting
Product is created twice
SKU/productNumber do not match – align the numbers and match the existing product.
Attribute not linked
The name differs (capitalization, spaces). Align the names and run the comparison again.
Variant is missing
The color/size property is not configured correctly – check the label and ID.
Image not imported
Retrieve the media info or set the default picture again.
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.