Demac Media Demac Media Brand Demac Media Brand



Upserting Product Images via the Magento API

Timer Icon 4 Mins

Magento Commerce

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:

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:

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.

    Subscribe to the Blog

    Stay updated with 20,000+ eCommerce leaders in our community

    Sign Up

    Let’s talk about your 10X return

    Icon/Social/Phone Contact us for pricing information