> 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-pictures.md).

# Item Pictures

Item pictures are essential for a professional online shop. The Shopware 6 API Connector lets you upload and manage product images directly from Business Central.

**1. Pictures in Business Central**

**1.1 Assigning a main image**

The main image of an item is managed on the **Item Card**:

{% columns %}
{% column %}
{% stepper %}
{% step %}
Open the *Item Card*.
{% endstep %}

{% step %}
In the picture area (on the right in the default view), click the *"Picture"* icon.
{% endstep %}

{% step %}
Select *"Import"* and upload an image.
{% endstep %}
{% endstepper %}
{% endcolumn %}

{% column %}

<div align="left" data-with-frame="true"><figure><img src="https://3167966143-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVsUTvHyq0bxTYi3oQtlM%2Fuploads%2FrOkWNNVT0mGiUtaqVDEI%2FBildschirmfoto%202026-04-07%20um%2011.45.23.png?alt=media&#x26;token=1f061538-a1e4-458f-9a1c-dee431c66753" alt="" width="375"><figcaption></figcaption></figure></div>
{% endcolumn %}
{% endcolumns %}

{% hint style="success" %}
You can change the cover image in BC at any time. After synchronization, the changes are automatically applied in Shopware.
{% endhint %}

**1.2 Additional images**

For additional product images (gallery):

{% stepper %}
{% step %}
Open the Item Card.
{% endstep %}

{% step %}
Again in the right-hand area (default view), you will find the *"Picture"* menu item. There, click the number shown to the right of *"Shopware Additional images"*.

{% hint style="info" %}
If no images other than the cover image have been uploaded, **0** is displayed. Otherwise, the number shown corresponds to the **total number of additionally uploaded images**.
{% endhint %}

<div align="left" data-with-frame="true"><figure><img src="https://3167966143-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVsUTvHyq0bxTYi3oQtlM%2Fuploads%2FJcuW6w8nnvgK5Fm5gKuH%2FBildschirmfoto%202026-04-09%20um%2009.33.00.png?alt=media&#x26;token=b1e15933-7a1c-46cc-884d-444bbc6495eb" alt="" width="121"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
A new "Additional Shopware Images" window opens. Here you can upload additional images and also edit or delete existing ones.

<div align="left" data-with-frame="true"><figure><img src="https://3167966143-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVsUTvHyq0bxTYi3oQtlM%2Fuploads%2FlTE0nrbL4EjYVTtQl5bm%2FBildschirmfoto%202026-04-09%20um%2009.33.23.png?alt=media&#x26;token=5c802819-275a-43ae-bdfe-58153765c96e" alt="" width="563"><figcaption><p><em>"Additional Shopware Images"</em> menu, view only</p></figcaption></figure></div>

To enable editing, click *"+ New"* or *"Edit List"**.*** Then click *"Shopware Product Images"* on the right and select *"Import"* to upload another image in addition to the existing cover image.

<div align="left" data-with-frame="true"><figure><img src="https://3167966143-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVsUTvHyq0bxTYi3oQtlM%2Fuploads%2FItiD5ytB4ze8nER4FGMA%2FBildschirmfoto%202026-04-09%20um%2009.33.45.png?alt=media&#x26;token=e3998d3f-a7a7-4f68-874f-799e00410042" alt="" width="563"><figcaption><p><em>"Additional Shopware Images"</em> menu, in edit mode</p></figcaption></figure></div>
{% endstep %}

{% step %}

<div align="left" data-with-frame="true"><figure><img src="https://3167966143-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVsUTvHyq0bxTYi3oQtlM%2Fuploads%2FIEf2ub7hnU3NOMxWJPhk%2FBildschirmfoto%202026-04-09%20um%2009.33.53.png?alt=media&#x26;token=155a7a78-3899-45fc-b041-88ee3e60898c" alt="" width="219"><figcaption><p>Opened window for the image upload</p></figcaption></figure></div>
{% endstep %}

{% step %}
Repeat steps 3 and 4 to upload further images (one image per line). In the example, three additional images were uploaded alongside the cover image. You can assign individual names in the *"Image SEO Description"* column.

<div align="left" data-with-frame="true"><figure><img src="https://3167966143-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVsUTvHyq0bxTYi3oQtlM%2Fuploads%2FdgOkugoDyAvxotNUVyAl%2FBildschirmfoto%202026-04-09%20um%2009.35.14.png?alt=media&#x26;token=c06c6419-473c-48c8-9671-2dd7120cbc59" alt="" width="513"><figcaption><p>Upload of three images with adjusted description</p></figcaption></figure></div>
{% endstep %}

{% step %}
👉 After you leave the menu, the number of additional images is displayed on the Item Card.

<div align="left" data-with-frame="true"><figure><img src="https://3167966143-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVsUTvHyq0bxTYi3oQtlM%2Fuploads%2FHVI8pBVvaTKhQ3NPaiNr%2FBildschirmfoto%202026-04-09%20um%2009.35.35.png?alt=media&#x26;token=42b64f0d-c9f5-4100-a8a4-2d25dbf2d89d" alt="" width="120"><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

{% hint style="success" %}
The same applies here: you can change the images in BC at any time. After synchronization, the changes are automatically applied in Shopware.
{% endhint %}

{% hint style="warning" %}
Images added manually in Shopware are not deleted automatically during synchronization.
{% endhint %}

**2. Supported image formats**

<table data-view="cards"><thead><tr><th align="center"></th><th align="center"></th><th align="center"></th></tr></thead><tbody><tr><td align="center">✅ Yes</td><td align="center"><p><i class="fa-file-jpg">:file-jpg:</i> <i class="fa-file-png">:file-png:</i> <i class="fa-newspaper">:newspaper:</i></p><p><strong>JPEG, PNG, WebP</strong></p></td><td align="center">5 MB</td></tr><tr><td align="center">⚠️ Limited</td><td align="center"><p><i class="fa-gif">:gif:</i></p><p><strong>GIF</strong></p></td><td align="center">2 MB</td></tr><tr><td align="center"></td><td align="center">Recommended resolution: at least <strong>800x800 pixels</strong> for a good presentation in Shopware.</td><td align="center"></td></tr></tbody></table>

**2. Image synchronization**

**2.1 Configuration**

{% stepper %}
{% step %}
Open *"Shopware"* <i class="fa-right">:right:</i> "*Settings"*.

<div align="left" data-with-frame="true"><figure><img src="https://3167966143-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVsUTvHyq0bxTYi3oQtlM%2Fuploads%2FT8ErsghIhhJiFeo53xED%2FBildschirmfoto%202026-04-09%20um%2010.15.47.png?alt=media&#x26;token=ec7e2431-8b62-42a4-b48a-be5d366cf22d" alt=""><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
There, in the *"Inventory Settings"*, the ***"Picture Folder ID"*** must be configured accordingly. Under *"Picture Folder ID"*, enter the ID of the Shopware media folder.

<div align="left" data-with-frame="true"><figure><img src="https://3167966143-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVsUTvHyq0bxTYi3oQtlM%2Fuploads%2FZu8g5diR5Kq5IIDrBMU8%2FBildschirmfoto%202026-04-09%20um%2010.20.41.png?alt=media&#x26;token=2aafc402-7461-4861-883c-e6489f8a197e" alt=""><figcaption><p>Inventory settings: <em>"Picture Folder ID"</em></p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

**2.2 Uploading a single image**

{% stepper %}
{% step %}
Open the Item Card.
{% endstep %}

{% step %}
Click *"Actions"* <i class="fa-right">:right:</i> *"Shopware"* <i class="fa-right">:right:</i> *"*<i class="fa-up">:up:</i> *Upload Product"*

The main image and all additional images are uploaded.

<div align="left" data-with-frame="true"><figure><img src="https://3167966143-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVsUTvHyq0bxTYi3oQtlM%2Fuploads%2FFhAGc4cpwaaEouZ7VaEJ%2FBildschirmfoto%202026-04-09%20um%2010.38.29.png?alt=media&#x26;token=3fc6aec5-f2b8-434b-8f29-2a27829d1de0" alt=""><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

**2.3 Uploading pictures for several items**

{% stepper %}
{% step %}
Open the item list (*"Sales"* <i class="fa-right">:right:</i> *"Items")*
{% endstep %}

{% step %}
Select the items you want. Click *"Actions"* <i class="fa-right">:right:</i> *"Shopware"* <i class="fa-right">:right:</i> *"Import Default Images".* The item pictures of the selected items are uploaded.

<div align="left" data-with-frame="true"><figure><img src="https://3167966143-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVsUTvHyq0bxTYi3oQtlM%2Fuploads%2Fz9UYsiZfwwgX0V5xh4Yj%2FBildschirmfoto%202026-04-09%20um%2010.41.52.png?alt=media&#x26;token=f5814e4d-3a86-453a-aaa8-ce7dbc6f48ff" alt=""><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

**3. Shopware media folder**

{% columns %}
{% column %}
**Folder structure**

Images are stored in the configured media folder:

```
Media/
├── Product Media/
│   ├── item-picture-001.jpg
│   ├── item-picture-002.jpg
│   └── ...
```

{% endcolumn %}

{% column %}
**Finding the folder ID**

1. Open the **Shopware backend**
2. Navigate to **Content** → **Media**
3. Click the folder you want.
4. You will find the ID in the URL.
   {% endcolumn %}
   {% endcolumns %}

**4. Tips for day-to-day work**

{% tabs %}
{% tab title="Image quality" %}

* Use high-resolution images (min. 800x800 px).
* Make sure image sizes are consistent.
* Optimize images for the web (compression).
  {% endtab %}

{% tab title="File naming" %}

* Use meaningful file names.
* Avoid special characters and umlauts.
* Example: `itemno-001-front.jpg`
  {% endtab %}

{% tab title="Performance" %}

* Upload images outside of peak hours.
* Compress large images before uploading.
* Monitor the Activity Log.
  {% endtab %}
  {% endtabs %}

### Frequently Asked Questions

#### How do the images get from Business Central to Shopware?

`ImportBaseImages` takes over the BC standard images as "SOUSHW Item Picture". `Upload_ItemImages` and `Upload_Media` then upload the files to Shopware via the `media` and `product-media` endpoints and assign them to the product; `SetCoverImage` defines the cover image.

#### Does the connector prevent the same image from being uploaded more than once?

Yes. Before the upload, `isFileNameAlreadyUploaded` uses `search/media` to check by file name whether the image already exists in Shopware. This prevents identical media from being created twice.


---

# 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-pictures.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.