Provide images for items and groups
The shop system typically stores one URL per image and serves the image through its proxy, scaled and cached (see file-proxy for the fetching side). This document is about the other direction: how an image URL gets attached to an item or a navigation level in the first place.
Every Item can carry a thumbnail (list view), a big image
(detail view) and up to nine extra images (gallery). Navigation levels —
Group, subgroup, Rubric (price list) and
Navigation entries — carry a small and a big image each. The API
objects only tell you that an image exists (thumbnailCode, imageCode, imageCount, the
image hash of a group); whether it does is decided by the sources below.
copying image data
Image files have to be stored somewhere; that is always a place "in the internet". So yu have to copy the file (e.g. from your camera) to a so-called web-space.
FTP, WebDAV or other protocols
These terms describe methods, to move a image file to such a place. Note that adresses and advice opjn how to do this differ, depending on your provider or tools. But in any case, the date that you transfer needs to be available using a regular http(s)-Web URL. After you transferred your image, always check that it is reachable using a web address.
Shop internal
if we are not talking about thousands of product images, you may use the internal storage of the shop systems admin area (Inhalte). After you upload it there, you are presented a web address that you can use with methods
- or 5) below.
The image file sources, in order of precedence
| # | Source | Items | Groups & navigation |
|---|---|---|---|
| 1 | Image mapping (shop setting) | ✓ | ✓ |
| 2 | URL entered in PCG | ✓ | ✓ |
| 3 | Automatic lookup on your webspace | ✓ | – |
| 4 | Shared product databases (oekobox, datanature, ecoinform) | ✓ | – |
| 5 | Generated images | – | ✓ |
A mapping entry wins over everything. Among the automatic sources the first one that finds an image wins, and an image that was found once is kept — a later run only fills gaps, it never removes an image (exceptions: PCG clears its URL, or an authoritative ecoinform record says so).
1. Enter the URL in the PCG backend
The simplest way, and the one that works for every entity. In the PCG item record there are two
fields, one for the big image and one for the thumbnail; groups, subgroups, price lists and
navigation entries have the same pair. Put the full, publicly reachable URL there
(https://www.myfarm.example/img/123.jpg). PCG transfers it with the next item update, and the
shop picks it up immediately.
- A URL from PCG has precedence over everything the automatic lookup or the product databases found. If you later empty the field in PCG, the automatic sources get their chance again.
- Both fields may point to the same file; the proxy scales on request. If only one is set the proxy falls back to the other one (thumbnail → big image, big image → thumbnail).
- The URL must answer with an image content type and without login. Redirects are not followed.
2. Automatic lookup on your own webspace
For shops with many items it is easier to drop files into a folder on the shop operator's own webspace (typically by FTP) and let the shop find them. Two settings in the shop admin, group Data Enrichment, define where to look:
| Setting | Finds |
|---|---|
| Image Server URL Pattern (big image) — German Bild-Url-Abruf (Großes Bild) | the big image, and extra images if {3} is used |
| Image URL Pattern — German Bild-Url-Abruf (Kleines Bild) | the thumbnail |
Each setting is a URL pattern with placeholders; several patterns can be given, comma separated, and are tried in order:
| Placeholder | Replaced by | Example pattern |
|---|---|---|
{0} |
the item id | https://www.myfarm.example/img/{0}.jpg → .../img/123.jpg |
{1} |
the item name | https://www.myfarm.example/img/{1}.jpg → .../img/Apfelsaft.jpg |
{2} |
the item's EAN | https://www.myfarm.example/img/ean/{2}.png → .../ean/4012345678901.png |
{3} |
the item id, plus _1 … _9 for the extra images |
https://www.myfarm.example/img/{3}.jpg |
Rules:
- The item id is the item number PCG shows; it is the most robust key. The item name
must match the file name exactly and is placed into the URL as it is: a name with spaces,
umlauts or other special characters does not form a valid URL and is skipped, so
{1}only works for plain ASCII names. EAN is handy when the images come from a supplier; an item without EAN finds nothing, an EAN containing spaces is skipped. - Only items that have no image yet are looked up, so a lookup never overwrites a URL from PCG. To re-check an item, clear its URL in PCG or use "Reload images" in the shop admin.
- Lower and upper case extensions are both tried (
.jpg/.JPG,.png/.PNG,.gif/.GIF), so files uploaded from Windows are found too. - The file counts only if your web server answers it with an image content type. Redirects (e.g. a server that "helpfully" guesses the file name) are treated as "not found".
- The folder must be reachable without login from the internet. It may be a plain web folder; no index listing is needed.
- Thumbnails should be square (see Image format); if you only maintain one file per item, point both settings at the same pattern.
When the lookup runs:
- Once per night for all items, and immediately for a single item after PCG changed it.
- The shop operator can trigger a full run for the shop at any time ("Reload images" in the shop admin setup). Runs for the same shop are not queued twice; wait for the first one to finish.
- The source that finally delivered each image is shown at the item in the shop admin, which is the first place to look when an image is "wrong".
3. Several images per item: the {3} placeholder
If the pattern for the big image contains {3} instead of {0}, the shop also looks for
extra images. For item 123 and the pattern https://www.myfarm.example/img/{3}.jpg it checks
.../img/123_1.jpg
.../img/123_2.jpg
...
.../img/123_9.jpg
and stops at the first file that is missing. The number of files found is published as
imageCount in the Item object; the images themselves are fetched as
b1.px … b9.px (see file-proxy). The primary big image is still
123.jpg (the plain id).
Don't forget:
- Number the files without gaps: with
123_1.jpgand123_3.jpgbut no123_2.jpg, only one extra image is counted.123_0.jpgis never looked at. imageCountis recounted for every item on every run (also when the item already has a big image), so adding or removing a file takes effect after the next nightly run or a "Reload images".- Extra images are only supported with a single big-image pattern. With several comma separated patterns the gallery is switched off.
- If an item has extra images but no primary big image,
b.pxfalls back to123_1.jpg. - Keep the same file extension for all images of an item; the pattern has exactly one.
4. Shared product databases
For branded goods the shop can take images from shared product databases: the platform's own item pool (matched by EAN), datanature (matched by EAN or the datanature id entered in PCG) and ecoinform (EAN or ecoinform id; requires the shop's ecoinform key). Which of them are consulted, and in which order, is the setting info source in the shop admin; ecoinform and datanature need a contract and are licensed for items the shop actually sells, nothing else.
These databases only fill gaps, so a good EAN on the item is all you need. They provide the primary big image and thumbnail, not extra images.
5. Image mapping: the manual override
The setting image mapping in the shop admin is a text block, one entry per line, that overrides the image of any object — items as well as groups, navigation entries, producers and so on — before any other logic is consulted:
# object code + id, then the URL, separated by a space
g123 https://www.myfarm.example/img/groups/vegetables-small.jpg
h123 https://www.myfarm.example/img/groups/vegetables-big.jpg
t4711 https://cdn.supplier.example/pics/4711-thumb.png
# variables
$base=https://www.myfarm.example/img
b4711 ${base}/4711-detail.jpg
# rewrite a fragment in ALL image URLs, e.g. after moving the webspace
!http://old-host.example/images/ https://www.myfarm.example/img/
The object codes are the proxy type codes (t item thumbnail, b item big image, b1…b9
extra images, g/h group small/big, s/u subgroup, r/v price list, m/n
navigation, …), listed in file-proxy. Lines starting with # are
comments.
Use it for the odd exception — a seasonal picture, a group image the backend can't hold, a
supplier picture you don't want to download — and for the ! rewrite after a server move. It
is not meant to maintain hundreds of items; use the webspace lookup for that. The mapping is
cached for up to a day on the server; a change may take that long to show.
This feature is useful also for external agencies, that can not sit in front af a backend PCG: give them Webadmin-Role in PCG, so they can manage the images without big coordination.
6. Generated images for navigation levels
If the setting AI image generation for navigation is switched on, a group, subgroup, price list or navigation entry without an image gets one generated from its name and description (the prompt is configurable). The result is stored in the shop's content area, where it can be deleted to trigger a new attempt with a changed prompt. Items are never generated.
Play with the Prompt in the system setup - this is a fast way to make your shop attractive even if not (all) images the navigation levels are ready!
Image format and size
The proxy scales every image down to what the frontend asks for, so the source only needs to be good — not small. Recommended:
| Recommendation | |
|---|---|
| Shape | Square (1:1). Thumbnails in lists, cart and app tiles are (typically) square; a non-square source is letter-boxed with a background colour or cropped by the frontend. Big images may be 4:3, but square is the safe choice for both. |
| Resolution | Rather more pixels than less: 1200×1200 for the big image and the extra images is a good target; the thumbnail may be the same file. Anything below ~400×400 looks blurry on a phone. |
| File type | JPEG for photos, PNG for graphics with transparency or text. Prefer both over WebP: WebP is served as it is — not scaled, not rotated, not blurred — so every client downloads the full file. GIF works but is limited to 256 colours. |
| File size | Not more than 200 KB per file. Compress JPEGs at quality 80–85; very large originals (several MB) are fetched slowly, cached in full and may be refused above a limit. A thumbnail above 150 KB is recompressed by the server anyway. |
| Colour | sRGB; embedded CMYK or exotic colour profiles come out wrong. |
| Orientation | Save the image upright. EXIF rotation is honoured, but not every editor writes it. |
Lower case file extensions matching the content (.jpg for JPEG) avoid surprises with the
content type check.
Changing an image
The shop and the browsers cache aggressively (see file-proxy). When you replace a file under the same name, the new picture appears after the next item update from PCG or after "clear cache" in the shop admin (for one item or the whole shop); the image hash in the API changes with it, so API clients get a new URL automatically. When you replace it under a new name, update the URL in PCG, or just drop the old file and let the lookup find the new one on the next run.
Don't forget
- Legal: you need the right to publish every picture. Supplier and stock photos usually come with a licence that excludes online shops or requires attribution; DataN>ature and ecoinform images are licensed for items the shop sells only.
- One source per item. Mixed setups (some items from PCG, some from the webspace, some from a database) are fine, but when an image is wrong, check the source shown at the item in the shop admin first instead of uploading another file that will never be picked up.
- No login, no redirect, correct content type on the webspace — the three reasons a file "that is clearly there" is not found. Following a redirect is often dangerous, as it might lead to an unexpected image or place.
- The "missing image" placeholder is configurable per shop. Set a neutral one so an item without a picture does not look broken.
- Groups do not get a lookup. Group, subgroup, price list and navigation images come from
PCG, from image mapping or from generation — not from a
{0}pattern. - API clients: read
thumbnailCode/imageCode/imageCountand pass the hash to the proxy; never guess that an image exists. See item-details.
Ideas
- A gallery on the item detail page: show
b.pxandb1.px…b<imageCount>.pxas a swipeable strip; the standard components show this (only) whenimageCount> 0 in the lower tabbed area. - Supplier image feeds: name the files by EAN on your webspace and use a
{2}pattern; a single folder then serves all items of that supplier without touching PCG. - Seasonal group pictures: keep two lines in the image mapping and comment one out.
- Webspace move: one
!old newrewrite line in the image mapping instead of re-entering hundreds of URLs in PCG.