Matrix Sub-Item Images Don’t Show by Default in NetSuite SCA

In NetSuite’s SuiteCommerce Advanced (SCA), managing product imagery for matrix items—especially sub-items—can be unintuitive. By default, images added to the “Related Images” field of a matrix sub-item do not appear on the website’s Product Detail Page (PDP). This behavior stems from how NetSuite handles image inheritance and rendering logic for matrix items.

🔍 Default Behavior Explained

• Matrix items consist of a parent item and multiple sub-items, each representing a variation (e.g., size, color).
• The “Related Images” field on sub-items is not automatically surfaced on the PDP unless explicitly configured.
• SCA typically pulls images from the parent item or uses a default image logic based on alphabetical order or item creation sequence.

🛠️ Why Customization Is Needed

To display sub-item-specific images (e.g., showing a red shirt when “Red” is selected), you’ll need to introduce a custom field and configure image rendering logic accordingly:

Recommended Customization Steps

1. Create a Custom Item Field

• Go to Customization > Item Fields > New
• Define a field like custitem_matrix_image_url or custitem_color_image_map
• Apply it to Inventory Items and Matrix Sub-Items

1. Upload and Map Images

• Store image URLs or file references in the new field
• Use a consistent naming convention (e.g., ItemName-Color-Size.jpg) to support dynamic rendering

1. Update PDP Rendering Logic

• Modify the PDP template to check for the custom field on the selected sub-item
• Use JavaScript to dynamically swap images based on selected matrix options

1. Enable Multi-Image Option Mapping

• Navigate to Commerce > Websites > Configuration
• Under Shopping Catalog > Multi-Image Option, map the custom transaction item options to enable dynamic image switching

⚠️ Common Pitfalls

• Image inheritance confusion: Parent item images may override sub-item visuals if not handled properly.
• Filename mismatches: Inconsistent naming can cause images to appear prematurely or not at all.
• Frontend limitations: Not all custom fields are exposed to the frontend without explicit configuration.