Renaming Image Files with an Item Identifier

This topic applies to

Applies to

SuiteCommerce Web Stores


The first step in setting up images for SuiteCommerce is to rename each of your image files with an item identifier.

Decide on a naming convention that includes an item identifier for image files intended for your SuiteCommerce website and rename image files accordingly. Use the Item Identifier field to choose a field on item records that NetSuite can use to link image files together with item records.


For custom fields, only stored custom fields are available to be used as an Item identifiers. If a custom field has the Store Value set to False in the custom field record, it is not available.

Image File Naming Guidelines

  • Append the item identifier to the beginning of the image file name you want associated with each item record. You can add to the filename of each image using the Item ID Delimiter and the Structure Delimiter.

    The example below shows the image file name format when the item identifier is set to UPC code:


  • The Item ID Delimiter is required. The default value is an underscore (_). It is used to parse the item identifier from the image filename.

  • The default value of the Structure Delimiter field is a single dash (-). The Structure delimiter can be used to add information to the image filename. You are not required to use the Structure Delimiter in your image file names, but the Structure Delimiter field requires a value to prevent the Item Search API from returning internal errors.

  • The image file naming convention you choose should make sense for your website.

  • The image file name should be unique, and the file name can have a maximum of two delimiters and three words.


    If you do not follow the image file naming guidelines, item images may not be returned in the search results even though the images have been associated with the item on the item record.

  • For images associated with items that have item options, you should use a non-numeric value after the last delimiter in the image file name.


    If you use a numeric value after the last delimiter, you might not be able to change item images in the web store when you change the item options. For example, sku12345_toySlide-9-blue.png and sku12345_toySlide-blue-size9.png are as per the image file naming guidelines but sku12345_toySlide-blue-9.png is not.


  • You can upload image files intended for different types of site templates. For example, if you create one site template for a list of search results, and another for the product detail view, then name image files accordingly:

  • You can upload different images optimized for various devices:

  • While adding multiple images of the same item, you should maintain uniqueness of the image file name. For example, you can maintain uniqueness while not exceeding the permitted delimiter and word limit as shown below:


    To designate one of these images to display by default on the product list page and first on the product detail page, see Setting a Default Image.

Notes on delimiters:

  • Delimiters parse the file name from the item identifier.

  • You can change the value for either of the Item ID or Structure delimiter. Both delimiters can be the same.

  • You can change the delimiters to any combination of up to five supported characters ($ - _ . + ! * ' ( ) ,). The maximum limit is five characters.

Setting a Default Image

When using two or more images for one product, you can designate one of the images as the default image. The default image displays on the product list page and first on the product details page. To designate an image as the default, add .default to the end of the file name.

In the following example, sku12345_toyslide-blueAltB.png is renamed to become the default image: sku12345_toySlide-blueAltB.default.png.


After you have decided on the naming convention for your site, and renamed all the image files, go to the next step in setting up image-product mapping for SuiteCommerce.