Images

How to send images

There are two ways to deliver images. Both can be used for the same product.

1. As a URL in the product (recommended). Put a public image URL in an image attribute when you create or update a product:

   "values": {
     "image_default": [ { "data": "https://cdn.example.com/products/tshirt-001-black-front.jpg", "locale": null } ],
     "image_1": [ { "data": "https://cdn.example.com/products/tshirt-001-black-back.jpg", "locale": null } ]
   }

The URL is checked straight away; an invalid URL is answered with 422. The image itself is downloaded later, in the background, and then reviewed by Winkelstraat before it appears on the product. A successful response therefore does not mean the image was accepted, and a failed download is not reported back through the API.

1. As a separate upload with POST /api/rest/v1/retailer/media-files, either as a file or as a URL. This call downloads or stores the image immediately and reports download problems in its response.

Image attributes

• image_default: the main image. It must always show the front of the item.
• image_1, image_2, …: additional images. GET /api/rest/v1/retailer/attributes lists all attributes of type pim_catalog_image.

Images belong to the product group (parent): all sizes share the same images. Sending an empty value ("data": null) removes the image.

Content requirements

• File format: JPG, PNG or WebP. Image URLs should end in .jpg, .png or .webp. A query string after the extension (for example .jpg?v=2) is accepted, but we advise against it.
• Resolution: we advise a minimum of 1000 × 1000 pixels.
• Sharpness: photos must stay sharp when zoomed in.
• Background: preferably white; light grey is also accepted. Dark backgrounds are rejected.
• Photography: only professional studio photography is accepted.
• Main image: always the front of the item, preferably a packshot or on a mannequin. A model photo is also allowed.
• Model photos: cropping between the nose and the lips is preferred. If needed, Winkelstraat can also do this during editing.
• Additional images: a photo of the back of the item is preferred. Detail shots are required for all items.
• Rejected: photos of samples or sketches, lifestyle images, and photos containing text (unless the text gives relevant product information).

Technical requirements for image URLs

• The URL must be a valid, publicly reachable http or https URL. No login, cookies or IP allow-listing.
• The server must respond within 10 seconds and deliver the complete image within 30 seconds, with a 2xx status code.
• The response must contain an image file. HTML pages, empty files and unknown file types are rejected with Image type is not supported.
• For images sent as a URL in the product, a temporary problem (timeout, 408, 429 or 5xx) is retried up to 3 times in total. Other 4xx responses are not retried.