REST Item Image

Create, list, update or delete item images. Item images are saved on the item level and are then linked to one or more variations of the item. Images can be uploaded in the file formats JPG, JPEG, PNG, GIF or SVG.
When an item image is uploaded to plentymarkets, different versions of the image are created and can be accessed using the parameters shown in brackets:

  • High-resolution item image (url)
  • Medium-sized item image (urlMiddle)
  • Two preview images (urlPreview, urlSecondPreview)
After uploading the image, names can be saved for the different languages in which items are offered for sale. Image names can be managed using the route Image Name.
By default, the uploaded image is made available for all clients and referrers in the system. The availability of the image for clients (stores) and referrers is managed using the route Item Image Availability.
Images are linked to one or more variations. These links are managed using the route Variation Image.

Upload a new image

Uploads an image. The item ID must be specified.

/rest/items/{id}/images/upload

Request

Field Type Description
itemId Int The ID of the item the image is associated with required
position Int The position of the image. The position is used for sorting images in the online store. optional
fileType String The file format of the image. Possible file formats: JPG, JPEG, PNG, GIF, SVG optional
uploadFileName String The file name assigned to the uploaded image. Permitted characters for file names: alphanumeric (a-z, A-Z, 0-9), hypens (-), underscores (_). required with uploadImageData
uploadImageData String The base64 encoded image data of the image
uploadUrl String The URL under which the image can be accessed for uploading. Permitted characters for file names: alphanumeric (a-z, A-Z, 0-9), hypens (-), underscores (_).
names \ItemImageName[] names optional array
 lang String The language of the image name required
 name String The name of the image in the specified language required
 alternate String The alternative name of the image in the specified language optional
availabilities \ItemImageAvailability[] availabilities optional array
 type String The type of referrer for which the image is available. Possible types:
  • mandant = The image can be made available for clients (stores).
  • marketplace = The image can be made available for markets.
  • listing = The image can be made available for listings.
required allowed values are mandant, marketplace, listing
 value Float For the type mandant, this is the plentyID of the client (store) for which the image is available. For the types marketplace and listing, this is the ID of the referrer for which the image is available.
  • -1.00 = The image is available for all referrers of this type.
required
{"position":45,"fileType":"gif","uploadFileName":"voluptas","uploadImageData":"VGhpc0lzTm90QVJlYWxJbWFnZQ==","names":[{"imageId":10,"lang":"tk","name":"quos"}],"availabilities":[{"imageId":6,"type":"listing","value":4}]}

Success 200

Field Type Description
id Int The unique ID of the image
itemId Int The unique ID of the item the image is associated with
fileType String The file format of the image. Possible file formats: jpg, jpeg, png, gif, svg
path String The path under which the image is saved.
position Int The position of the image. The position is used for sorting images in the online store.
createdAt String The time the image was uploaded.
updatedAt String The time the image details were last updated.
md5Checksum String The MD5 hash value of the image file
md5ChecksumOriginal String The MD5 hash value of the original image file
size Int The size of the image in pixels
width Int The width of the image in pixels
height Int The height of the image in pixels
url String The URL under which the image can be accessed after the upload.
urlMiddle String The URL that points to the medium-sized version of the item image.
urlPreview String The URL that points to the first preview version of the item image.
urlSecondPreview String The URL that points to the second preview version of the item image.
names \ItemImageName[] Lists the image's name details as an array. (List)
 imageId Int The ID of the image. The ID must be unique.
 lang String The language of the image name
 name String The name of the image in the specified language
 alternate String The alternative name of the image in the specified language
availabilities \ItemImageAvailability[] Lists the image's availability details as an array. (List)
 imageId Int The ID of the image. The ID must be unique.
 type String The type of referrer for which the image is available. Possible types:
  • mandant = The image can be made available for clients (stores).
  • marketplace = The image can be made available for markets.
  • listing = The image can be made available for listings.
 value Float For the type mandant, this is the plentyID of the client (store) for which the image is available. For the types marketplace and listing, this is the ID of the referrer for which the image is available.
  • -1.00 = The image is available for all referrers of this type.
{"itemId":110,"fileType":"gif","path":"\/example\/to\/image\/10\/100\/100-aperiam.gif","position":20,"createdAt":"2000-02-24T23:58:58+01:00","updatedAt":"2011-06-10T06:42:01+02:00","md5Checksum":"8a53a059c8084ed127beea573549e37f","id":15,"availabilities":[{"imageId":15,"type":"marketplace","value":6}],"names":[{"imageId":15,"lang":"ig","name":"pariatur"}]}

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

List images of an item

Lists all images of an item. The item ID must be specified.

/rest/items/{id}/images

Parameters

Field Type Description
updatedAt String Filter restricts the list of results to items updated after the specified date. The date can be specified as unix timestamps or in the ISO 8601 date format. The PHP function strtotime is also supported.

Success 200

Field Type Description
id Int The unique ID of the image
itemId Int The unique ID of the item the image is associated with
fileType String The file format of the image. Possible file formats: jpg, jpeg, png, gif, svg
path String The path under which the image is saved.
position Int The position of the image. The position is used for sorting images in the online store.
createdAt String The time the image was uploaded.
updatedAt String The time the image details were last updated.
md5Checksum String The MD5 hash value of the image file
md5ChecksumOriginal String The MD5 hash value of the original image file
size Int The size of the image in pixels
width Int The width of the image in pixels
height Int The height of the image in pixels
url String The URL under which the image can be accessed after the upload.
urlMiddle String The URL that points to the medium-sized version of the item image.
urlPreview String The URL that points to the first preview version of the item image.
urlSecondPreview String The URL that points to the second preview version of the item image.
names \ItemImageName[] Lists the image's name details as an array. (List)
 imageId Int The ID of the image. The ID must be unique.
 lang String The language of the image name
 name String The name of the image in the specified language
 alternate String The alternative name of the image in the specified language
availabilities \ItemImageAvailability[] Lists the image's availability details as an array. (List)
 imageId Int The ID of the image. The ID must be unique.
 type String The type of referrer for which the image is available. Possible types:
  • mandant = The image can be made available for clients (stores).
  • marketplace = The image can be made available for markets.
  • listing = The image can be made available for listings.
 value Float For the type mandant, this is the plentyID of the client (store) for which the image is available. For the types marketplace and listing, this is the ID of the referrer for which the image is available.
  • -1.00 = The image is available for all referrers of this type.
[{"itemId":106,"fileType":"png","path":"\/example\/to\/image\/10\/100\/100-tempore.png","position":41,"createdAt":"2017-06-26T15:27:37+02:00","updatedAt":"2018-12-07T12:05:40+01:00","md5Checksum":"3f7c7d60330b4de560513813e145f583","id":39,"availabilities":[{"imageId":39,"type":"mandant","value":7}],"names":[{"imageId":39,"lang":"eo","name":"dolores"}]},{"itemId":108,"fileType":"png","path":"\/example\/to\/image\/10\/100\/100-aliquam.png","position":14,"createdAt":"1986-07-01T11:14:14+02:00","updatedAt":"1994-10-28T04:13:19+01:00","md5Checksum":"4ad083ed927c2a3ccee27697d759831d","id":36,"availabilities":[{"imageId":36,"type":"listing","value":1}],"names":[{"imageId":36,"lang":"oj","name":"laboriosam"}]}]

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Get an image

Gets an image. The ID of the image must be specified.

/rest/items/{id}/images/{imageId}

Success 200

Field Type Description
id Int The unique ID of the image
itemId Int The unique ID of the item the image is associated with
fileType String The file format of the image. Possible file formats: jpg, jpeg, png, gif, svg
path String The path under which the image is saved.
position Int The position of the image. The position is used for sorting images in the online store.
createdAt String The time the image was uploaded.
updatedAt String The time the image details were last updated.
md5Checksum String The MD5 hash value of the image file
md5ChecksumOriginal String The MD5 hash value of the original image file
size Int The size of the image in pixels
width Int The width of the image in pixels
height Int The height of the image in pixels
url String The URL under which the image can be accessed after the upload.
urlMiddle String The URL that points to the medium-sized version of the item image.
urlPreview String The URL that points to the first preview version of the item image.
urlSecondPreview String The URL that points to the second preview version of the item image.
names \ItemImageName[] Lists the image's name details as an array. (List)
 imageId Int The ID of the image. The ID must be unique.
 lang String The language of the image name
 name String The name of the image in the specified language
 alternate String The alternative name of the image in the specified language
availabilities \ItemImageAvailability[] Lists the image's availability details as an array. (List)
 imageId Int The ID of the image. The ID must be unique.
 type String The type of referrer for which the image is available. Possible types:
  • mandant = The image can be made available for clients (stores).
  • marketplace = The image can be made available for markets.
  • listing = The image can be made available for listings.
 value Float For the type mandant, this is the plentyID of the client (store) for which the image is available. For the types marketplace and listing, this is the ID of the referrer for which the image is available.
  • -1.00 = The image is available for all referrers of this type.
{"itemId":105,"fileType":"jpeg","path":"\/example\/to\/image\/10\/100\/100-praesentium.jpeg","position":39,"createdAt":"1985-06-04T12:26:45+02:00","updatedAt":"2005-12-13T16:26:50+01:00","md5Checksum":"37325e7ba05753a3bfe17c4229b31fcc","id":26,"availabilities":[{"imageId":26,"type":"marketplace","value":10}],"names":[{"imageId":26,"lang":"sq","name":"fugiat"}]}

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Update an image

Updates an image. The ID of the image must be specified.

/rest/items/{id}/images/{imageId}

Request

Field Type Description
itemId Int The unique ID of the item the image is associated with required
position Int The position of the image. The position is used for sorting images in the online store. optional
fileType String The file format of the image. Possible file formats: jpg, jpeg, png, gif, svg optional
{"position":29}

Success 200

Field Type Description
id Int The unique ID of the image
itemId Int The unique ID of the item the image is associated with
fileType String The file format of the image. Possible file formats: jpg, jpeg, png, gif, svg
path String The path under which the image is saved.
position Int The position of the image. The position is used for sorting images in the online store.
createdAt String The time the image was uploaded.
updatedAt String The time the image details were last updated.
md5Checksum String The MD5 hash value of the image file
md5ChecksumOriginal String The MD5 hash value of the original image file
size Int The size of the image in pixels
width Int The width of the image in pixels
height Int The height of the image in pixels
url String The URL under which the image can be accessed after the upload.
urlMiddle String The URL that points to the medium-sized version of the item image.
urlPreview String The URL that points to the first preview version of the item image.
urlSecondPreview String The URL that points to the second preview version of the item image.
names \ItemImageName[] Lists the image's name details as an array. (List)
 imageId Int The ID of the image. The ID must be unique.
 lang String The language of the image name
 name String The name of the image in the specified language
 alternate String The alternative name of the image in the specified language
availabilities \ItemImageAvailability[] Lists the image's availability details as an array. (List)
 imageId Int The ID of the image. The ID must be unique.
 type String The type of referrer for which the image is available. Possible types:
  • mandant = The image can be made available for clients (stores).
  • marketplace = The image can be made available for markets.
  • listing = The image can be made available for listings.
 value Float For the type mandant, this is the plentyID of the client (store) for which the image is available. For the types marketplace and listing, this is the ID of the referrer for which the image is available.
  • -1.00 = The image is available for all referrers of this type.
{"itemId":107,"fileType":"jpg","path":"\/example\/to\/image\/10\/100\/100-perferendis.jpg","position":41,"createdAt":"1981-08-12T08:06:38+02:00","updatedAt":"2001-10-25T20:30:45+02:00","md5Checksum":"239c5cabaa7ad488945de61459169232","id":38,"availabilities":[{"imageId":38,"type":"listing","value":7}],"names":[{"imageId":38,"lang":"fr","name":"deleniti"}]}

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Delete an image

Delete an image. The ID of the image must be specified.

/rest/items/{id}/images/{imageId}

Success 200

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

List images of a variation

Lists all images of a variation. The variation ID must be specified.

/rest/items/{id}/variations/{variationId}/images

Success 200

Field Type Description
id Int The unique ID of the image
itemId Int The unique ID of the item the image is associated with
fileType String The file format of the image. Possible file formats: jpg, jpeg, png, gif, svg
path String The path under which the image is saved.
position Int The position of the image. The position is used for sorting images in the online store.
createdAt String The time the image was uploaded.
updatedAt String The time the image details were last updated.
md5Checksum String The MD5 hash value of the image file
md5ChecksumOriginal String The MD5 hash value of the original image file
size Int The size of the image in pixels
width Int The width of the image in pixels
height Int The height of the image in pixels
url String The URL under which the image can be accessed after the upload.
urlMiddle String The URL that points to the medium-sized version of the item image.
urlPreview String The URL that points to the first preview version of the item image.
urlSecondPreview String The URL that points to the second preview version of the item image.
names \ItemImageName[] Lists the image's name details as an array. (List)
 imageId Int The ID of the image. The ID must be unique.
 lang String The language of the image name
 name String The name of the image in the specified language
 alternate String The alternative name of the image in the specified language
availabilities \ItemImageAvailability[] Lists the image's availability details as an array. (List)
 imageId Int The ID of the image. The ID must be unique.
 type String The type of referrer for which the image is available. Possible types:
  • mandant = The image can be made available for clients (stores).
  • marketplace = The image can be made available for markets.
  • listing = The image can be made available for listings.
 value Float For the type mandant, this is the plentyID of the client (store) for which the image is available. For the types marketplace and listing, this is the ID of the referrer for which the image is available.
  • -1.00 = The image is available for all referrers of this type.
[{"itemId":103,"fileType":"png","path":"\/example\/to\/image\/10\/100\/100-quis.png","position":45,"createdAt":"1992-01-10T08:24:36+01:00","updatedAt":"2003-02-02T15:51:56+01:00","md5Checksum":"a40dc76f3a683429ba0ad4711506309c","id":12,"availabilities":[{"imageId":12,"type":"mandant","value":7}],"names":[{"imageId":12,"lang":"sl","name":"et"}]},{"itemId":107,"fileType":"svg","path":"\/example\/to\/image\/10\/100\/100-quia.svg","position":21,"createdAt":"1991-08-13T21:15:05+02:00","updatedAt":"1995-08-21T04:44:05+02:00","md5Checksum":"d7563d0a8c0b1655e76411632151bb49","id":35,"availabilities":[{"imageId":35,"type":"listing","value":9}],"names":[{"imageId":35,"lang":"tw","name":"in"}]}]

Errors 4xx

Code Exception Description
401 League\OAuth2\Server\Exception\AccessDeniedException The resource owner or authorization server denied the request.
401 League\OAuth2\Server\Exception\InvalidRequestException The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.

Is this article helpful?

 

Thank you for your Feedback

you can close this field now!