Upserting Product Images via the Magento API

Product images are an integral part of your product data. You don’t need A/B tests to determine that without product images, you will have terrible conversion rates. Magento’s API has the ability to create/update images, and it’s very important to know which action you are doing before you try to perform any of them! Learn about Upserting Product Images in Magento.

What is Upserting? According to

“Upsert is a merging of the words insert and update. This call is available for objects if the object has an external ID field or a field with the idLookup field property.”

Note: Magento will remove some characters in file names (/ \ ‘ as an example). Characters that really shouldn’t be in a filename anyways, but it’s important to note that your logic might break if you’re dealing with filenames that include any of these characters.

Obtain a list of product images

The first step we take is to get a list of the current images a product has. The method we use is

catalogProductAttributeMediaList(SessionKey, identifier, storeview, identifiertype);

From the data you get back from this API call, you can do compares on the file you want to upload and what is already uploaded to determine if your current image is a create or an update.

The object used to help with image upload is


This Object Has the Following Properties:

  • exclude : A 0 or 1 string which determines whether this should be shown or not.
  • label : The label associated to the image. Usually used for tooltips.
  • position : The sort order of the image in relation to the other images for this product.
  • types : An array of string that determines whether or not the current image is the default image shown upon load. One image technically has 3 differently sized images associated to it.

There is a lot of room for flexibility here to allow specific images to show by default for specific points of the site. There are three valid values:

  • image“: The main image, the one you will likely use the most often
  • small_image“: A scaled down version of image, generally used for previews
  • thumbnail“: The smallest size

Recently, I had to differentiate the default types between different images. One configurable product could be varied by many different colours. Each colour had colour swatches specifically related to that product. We obviously don’t want the swatch to be the main image, but we needed a very easy way to grab the swatches to display on the site. I had set the main image with types “image” and “small_image”, and the swatches with “thumbnail”. After that it’s just as easy as grabbing all the default thumbnails for that product. Declaring default types can be a smart way to make a seemingly complex task into a trivial one. It is powerful when used with some creativity.

The last property is “file” which takes the object type


The Properties Are:

  • name: The name of the file as it is uploaded to Magento. These means you can name your images a different filename then how they appear on your local drive. Something to potentially be careful of.
  • mime: MIME type. We use a standard “image/jpeg”. jpegs are light on file size and can hold great detail. Magento loves jpegs. I would recommend converting different image types to jpeg. Load times are crucial to your site and jpegs ensure light load.
  • content: This is where you place the actual image, but this property takes a string. You’ll have to convert your image to Base64 to upload it to Magento.
  • How to load the content property

    1. Load your image into
    2. Open up a
    3. “Save” the image into the MemoryStream
      image.Save(MemoryStream, ImageFormat)
    4. Convert the MemoryStream into Base64

    All of these methods are built into C#.

    What’s left to do?

    Once you’ve filled up your object properly it’s just a matter of calling Update or Create!

    catalogProductAttributeMediaUpdate(SessionKey, identifier, filenameOnMagento, catalogProductAttributeMediaCreateEntity, storeview, identifierType);


    catalogProductAttributeMediaCreate(SessionKey, identifier, catalogProductAttributeMediaCreateEntity, storeview, identifierType);

    There is not a whole lot to the process, but there are a fair amount of gotcha’s that can make you upload in unexpected ways if you’re not prepared for them.