Working with Matrix Items in SOAP web services

Before working with matrix items in SOAP web services, you must first enable the Matrix Item feature in your NetSuite account. To enable this feature go to Setup > Company > Enable Features, on the Items & Inventory subtab, select the Matrix Items check box.

This section covers the following topics:


For general information about the matrix items feature, see Matrix Items.

Item Types that Support Matrix Options

You can use SOAP web services to create matrix items for the following record types:

Note that item types that supports matrix options includes the following elements:

Creating a Parent Matrix Item

Users must set the matrixType field if they want to specify an item as either a parent or child matrix item.


This is a deviation from the UI behavior. In the UI you cannot create a parent matrix item without selecting the child options, however, in SOAP web services this is possible.

Creating a Child Matrix Item

Assuming that users have already setup matrix item options in their account, they can proceed with creating child matrix items. As opposed to the UI where selecting matrix options on the parent will result in creating the matrix children, in SOAP web services the user has to add each child matrix item separately.

The user must set the RecordRef of the parent (Subitem of) field and specify one or more matrix options for the matrix child item record. Note that the parent item must have the is MatrixParent field set to true, otherwise the following error is thrown:


Error message = Item {1} is not a parent matrix item.

Users can set also set the externalId field to submit parent matrix item data and associate the child matrix items with the parent in a single addList request in SOAP web services.


A maximum of 2000 children are permitted for a parent item.

Specifying Matrix Options

A call to getCustomization(“itemOptionCustomField”) can be used to return valid matrix option fields and values. A get on the parent matrix item returns only the matrix options that have been used. Not all possible options are returned.

Matrix Dimensions

After the first child is created, the dimensions for the matrix item are set and can not be changed. For example, if users creates a large, blue dress as the first child matrix item, they cannot subsequently create a dress that has any property other than size and color. A small, red, cotton dress will not be a valid option.

If users try to add a new child matrix with options that already exists for the parent, they will receive an error.

Updating Child and Parent Matrix Items

Users cannot update child matrix items through the parent record. Users must submit updates for child items individually.

For example, in SOAP web services, updating parent item values for the Asset Account, Cost of Goods Sold (COGS) account, or Income Account fields does not automatically update child item field values. You need to set these values for each child item row. The system does not enforce that child item values match the parent item values for these fields, so you need to ensure that they match yourself.

Also note that the following error is thrown if users attempt to update an existing item to make it a parent.

          Error Code = USER_ERROR
Error Message = You can not change an existing item to make it a parent matrix item {1}. 


The values that are returned in MatrixOptionList are read-only after the child matrix item is added.

Deleting Child and Parent Matrix Items

In SOAP web services users cannot delete a parent item if it has children. They must delete the child items individually before deleting the parent.

A check for child matrix items occurs on a request to delete a parent matrix item. If no children exist, the parent item is deleted. If children do exist, an error is returned stating that the parent has child items.

Matrix Item Code Sample

SOAP Request

          <?xml version="1.0" encoding="UTF-8"?>
   <soapenv:Envelope xmlns:soapenv="" xmlns:xsd="" xmlns:xsi=""> 
         <addList xmlns="">   
            <record externalId="parentSweater" xsi:type="ns1:InventoryItem" xmlns:ns1="">    
               <ns1:matrixType xsi:type="ns2:ItemMatrixType" xmlns:ns2="">_parent</ns1:matrixType>    
               <ns1:itemId xsi:type="xsd:string">sweater</ns1:itemId>   
            <record externalId="sweater-Red-Large" xsi:type="ns3:InventoryItem" xmlns:ns3="">    
               <ns3:matrixType xsi:type="ns4:ItemMatrixType" xmlns:ns4="">_child</ns3:matrixType>    
               <ns3:itemId xsi:type="xsd:string">sweater-Red-Large</ns3:itemId>    
               <ns3:parent externalId="parentSweater" xsi:type="ns5:RecordRef" xmlns:ns5=""/>    
               <ns3:matrixOptionList xsi:type="ns3:MatrixOptionList">     
                  <ns3:matrixOption scriptId="CUSTITEM_COLOR" xsi:type="ns6:SelectCustomFieldRef" xmlns:ns6="">      
                     <ns6:value internalId="1" typeId="1" xsi:type="ns6:ListOrRecordRef">       
                        <ns6:name xsi:type="xsd:string">Red</ns6:name>      
                  <ns3:matrixOption scriptId="CUSTITEM_SIZE" xsi:type="ns7:SelectCustomFieldRef" xmlns:ns7="">      
                     <ns7:value internalId="2" typeId="2" xsi:type="ns7:ListOrRecordRef">       
                        <ns7:name xsi:type="xsd:string">Large</ns7:name>      
            <record externalId="sweater-Green-Small" xsi:type="ns8:InventoryItem" xmlns:ns8="">    
               <ns8:matrixType xsi:type="ns9:ItemMatrixType" xmlns:ns9="">_child</ns8:matrixType>    
               <ns8:itemId xsi:type="xsd:string">sweater-Green-Small</ns8:itemId>    
               <ns8:parent externalId="parentSweater" xsi:type="ns10:RecordRef" xmlns:ns10=""/>    
               <ns8:matrixOptionList xsi:type="ns8:MatrixOptionList">     
                  <ns8:matrixOption scriptId="CUSTITEM_COLOR" xsi:type="ns11:SelectCustomFieldRef" xmlns:ns11="">      
                     <ns11:value internalId="2" typeId="1" xsi:type="ns11:ListOrRecordRef">       
                        <ns11:name xsi:type="xsd:string">Green</ns11:name>      
                  <ns8:matrixOption scriptId="CUSTITEM_SIZE" xsi:type="ns12:SelectCustomFieldRef" xmlns:ns12="">      
                     <ns12:value internalId="3" typeId="2" xsi:type="ns12:ListOrRecordRef">       
                        <ns12:name xsi:type="xsd:string">Small</ns12:name>      
            <record externalId="sweater-Blue-Large" xsi:type="ns13:InventoryItem" xmlns:ns13="">    
               <ns13:matrixType xsi:type="ns14:ItemMatrixType" xmlns:ns14="">_child</ns13:matrixType>    
               <ns13:itemId xsi:type="xsd:string">sweater-Blue-Large</ns13:itemId>    
               <ns13:parent externalId="parentSweater" xsi:type="ns15:RecordRef" xmlns:ns15=""/>    
               <ns13:matrixOptionList xsi:type="ns13:MatrixOptionList">     
                  <ns13:matrixOption scriptId="CUSTITEM_COLOR" xsi:type="ns16:SelectCustomFieldRef" xmlns:ns16="">      
                     <ns16:value internalId="3" typeId="1" xsi:type="ns16:ListOrRecordRef">       
                        <ns16:name xsi:type="xsd:string">Blue</ns16:name>      
                  <ns13:matrixOption scriptId="CUSTITEM_SIZE" xsi:type="ns17:SelectCustomFieldRef" xmlns:ns17="">      
                     <ns17:value internalId="2" typeId="2" xsi:type="ns17:ListOrRecordRef">       
                        <ns17:name xsi:type="xsd:string">Large</ns17:name>      
            <record externalId="sweater-Red-Small" xsi:type="ns18:InventoryItem" xmlns:ns18="">    
               <ns18:matrixType xsi:type="ns19:ItemMatrixType" xmlns:ns19="">_child</ns18:matrixType>    
               <ns18:itemId xsi:type="xsd:string">sweater-Red-Small</ns18:itemId>    
               <ns18:parent externalId="parentSweater" xsi:type="ns20:RecordRef" xmlns:ns20=""/>    
               <ns18:matrixOptionList xsi:type="ns18:MatrixOptionList">     
                  <ns18:matrixOption scriptId="CUSTITEM_COLOR" xsi:type="ns21:SelectCustomFieldRef" xmlns:ns21="">      
                     <ns21:value internalId="1" typeId="1" xsi:type="ns21:ListOrRecordRef">       
                        <ns21:name xsi:type="xsd:string">Red</ns21:name>      
                  <ns18:matrixOption scriptId="CUSTITEM_SIZE" xsi:type="ns22:SelectCustomFieldRef" xmlns:ns22="">      
                     <ns22:value internalId="3" typeId="2" xsi:type="ns22:ListOrRecordRef">       
                        <ns22:name xsi:type="xsd:string">Small</ns22:name>      
            <record externalId="sweater-Green-Large" xsi:type="ns23:InventoryItem" xmlns:ns23="">    
               <ns23:matrixType xsi:type="ns24:ItemMatrixType" xmlns:ns24="">_child</ns23:matrixType>    
               <ns23:itemId xsi:type="xsd:string">sweater-Green-Large</ns23:itemId>    
               <ns23:parent externalId="parentSweater" xsi:type="ns25:RecordRef" xmlns:ns25=""/>    
               <ns23:matrixOptionList xsi:type="ns23:MatrixOptionList">     
                  <ns23:matrixOption scriptId="CUSTITEM_COLOR" xsi:type="ns26:SelectCustomFieldRef" xmlns:ns26="">      
                     <ns26:value internalId="2" typeId="1" xsi:type="ns26:ListOrRecordRef">       
                        <ns26:name xsi:type="xsd:string">Green</ns26:name>      
                  <ns23:matrixOption scriptId="CUSTITEM_SIZE" xsi:type="ns27:SelectCustomFieldRef" xmlns:ns27="">      
                     <ns27:value internalId="2" typeId="2" xsi:type="ns27:ListOrRecordRef">       
                        <ns27:name xsi:type="xsd:string">Large</ns27:name>      
            <record externalId="sweater-Blue-Small" xsi:type="ns28:InventoryItem" xmlns:ns28="">    
               <ns28:matrixType xsi:type="ns29:ItemMatrixType" xmlns:ns29="">_child</ns28:matrixType>    
               <ns28:itemId xsi:type="xsd:string">sweater-Blue-Small</ns28:itemId>    
               <ns28:parent externalId="parentSweater" xsi:type="ns30:RecordRef" xmlns:ns30=""/>    
               <ns28:matrixOptionList xsi:type="ns28:MatrixOptionList">     
                  <ns28:matrixOption scriptId="CUSTITEM_COLOR" xsi:type="ns31:SelectCustomFieldRef" xmlns:ns31="">      
                     <ns31:value internalId="3" typeId="1" xsi:type="ns31:ListOrRecordRef">       
                        <ns31:name xsi:type="xsd:string">Blue</ns31:name>      
                  <ns28:matrixOption scriptId="CUSTITEM_SIZE" xsi:type="ns32:SelectCustomFieldRef" xmlns:ns32="">      
                     <ns32:value internalId="3" typeId="2" xsi:type="ns32:ListOrRecordRef">
                        <ns32:name xsi:type="xsd:string">Small</ns32:name>      



          /** Create Sweaters as matrix items.
* First create the parent - no matrix properties except "Matrix Type" is Parent
* Second create the matrix children with a combination of sizes and colors.
* This can be done in a single addList (as shown). 
//Define mrr method
public static RecordRef mrr(String internalId)
  RecordRef toRet = new RecordRef();
  return toRet;
// Define makeListOrRecordRef method
public static ListOrRecordRef makeListOrRecordRef(String sTypeId, String internalId, String sName)
  ListOrRecordRef toRet = new ListOrRecordRef();
  return toRet;
public void testMatrixSample() throws Exception
// Color is a Custom List of TypeId/RecType 1 that has already been created. 1,2,3 represent the
// internalIds of Red, Green, Blue
ListOrRecordRef[] colorArray = new
   ListOrRecordRef[] {makeListOrRecordRef("1","1","Red"), makeListOrRecordRef("1","2","Green"),
   makeListOrRecordRef("1","3","Blue")}; // Representing red, green and blue
// Size is a CustomList of TypeId/RecType 2 that has already been created
ListOrRecordRef[] sizeArray = new ListOrRecordRef[]{makeListOrRecordRef("2","2","Large"),makeListOrRecordRef("2","3","Small")};

//Representing large and small
      InventoryItem[] toSubmit = new InventoryItem[1+colorArray.length*sizeArray.length];
      toSubmit[0] = new InventoryItem();
      // set other fields on the Parent

      for (int i=0;i<colorArray.length*sizeArray.length;i++)
         toSubmit[i+1] = new InventoryItem();
         // mrr Creates a recordRef given an internal and externalId, the latter of which we specify.
         // This makes it so we can submit all the records at one time
         // "sweater-large-red","sweater-large-green"...
         toSubmit[i+1].setItemId("sweater-"+colorArray[i%3].getName() + "-" + 
            sizeArray[i % 2].getName());
         // set externalId so it's easier to find later
         // CUSTITEM_COLOR,SIZE are the names of the Item Custom Fields, applied to
         //InventoryItem that were setup as a Matrix types.
         SelectCustomFieldRef colorRef = new SelectCustomFieldRef();
         SelectCustomFieldRef sizeRef = new SelectCustomFieldRef();
         toSubmit[i+1].setMatrixOptionList(new MatrixOptionList(new
         // Set other matrix item child files
      WriteResponseList wr = c.getPort().addList(toSubmit);


Working with the Pricing Matrix

The following method takes an InventoryItem record and sets its pricing matrix. It sets the base price at quantity 0. If an invalid price was entered (a non-numeric value), it does not set the pricing matrix.

Sample Java Code

          private void createPricingMatrix(InventoryItem item)
   _console.write("\nPlease enter the base price: ");
   String priceString = _console.readLn();
   Price[] prices = new Price[1];
   prices[0] = new Price();

   PriceList priceList = new PriceList();

   Pricing[] pricing = new Pricing[1];
   pricing[0] = new Pricing();
   RecordRef priceLevel = new RecordRef();
   RecordRef currUSD = new RecordRef();

   PricingMatrix pricingMatrix = new PricingMatrix();

   catch (NumberFormatException e)
      _console.error("\nInvalid base price entered: " + priceString + ".  
         Proceed creating item without setting pricing matrix.");


Related Topics

Usage Notes for Item Record Types
Shared Field Definitions for Items
Item Search
How to Use the SOAP Web Services Records Help
SOAP Web Services Supported Records
SOAP Schema Browser
SuiteTalk SOAP Web Services Platform Overview

General Notices