How to import a matrix parent and its child items from CSV files in NetSuite

The screenshots show sample data. Person and company names are fictional. Use your own item, option field and values when following the steps.

Before you start

Example Supply Co. is adding a Web Strap in 1 inch and 2 inch widths. The account needs the Matrix Items feature, under Setup > Company > Enable Features > Items & Inventory, and a custom item field marked as a matrix option, here Width, with a custom list of values. A value in the file has to match a value in that list exactly. A parent can have up to 2,000 children in total.

Prepare two CSV files. Every row, parent or child, needs its own required item fields, such as Item Name/Number, Tax Schedule and the accounts your item type needs. The parent's accounts are not copied to its children during an import, so repeat them, and any other required field, on every child row. Your role needs permission to import records and add items.

01. Import the parent

The parent file has one row. Item Name/Number is Web Strap, and Matrix Type is Parent Matrix Item. It has no Subitem Of and no option values, because the parent holds no single value.

Enlarge

Go to Setup > Import/Export > Import CSV Records. Set Import Type to Items, so Record Type is Inventory Item, select the file and click Next. Keep Data Handling on Add and click Next.

Field Mapping proposes a pair for each header, including Matrix Type to Item : Matrix Type. Click Next, name the mapping, and click Save & Run. On Import Job Status, the job reads Complete with 1 of 1 records imported successfully.

Enlarge

02. Read the parent's internal ID

The child rows will name the parent by internal ID. Show internal IDs with Home > Set Preferences > Show Internal IDs, or read the id= value in the address of the item record. On Lists > Accounting > Items with the Internal ID column showing, Web Strap is 3610. Opening Web Strap shows the Matrix tag beside its name, which marks a matrix parent, and no children yet.

Enlarge

03. Import the children

The children file has one row per child. Matrix Type is Child Matrix Item, Subitem Of is 3610, and Matrix Option - Width holds one value, 1 inch or 2 inch. Name the option column exactly like the NetSuite field, Matrix Option - Width, so it maps itself. A column headed only Width maps to the ordinary custom field of that name, which doesn't set the matrix option.

Enlarge

Start Import CSV Records again with Items, Inventory Item, this file and Data Handling Add. Field Mapping proposes Subitem Of to Item : Subitem of and Matrix Option - Width to Item : Matrix Option - Width.

Enlarge

Subitem of is read by name unless you say otherwise, and a name did not find the matrix parent in this account. Click the pencil on the Subitem of row and set Choose Reference Type to Internal ID, then click OK. If you type a name, the rows fail with an invalid parent reference key.

Enlarge

Click Next, name the mapping, and click Save & Run. Import Job Status now lists both jobs as Complete: 1 of 1 records for the parent and 2 of 2 for the children. Open CSV Response if a row fails.

Enlarge

04. Check the parent

Open Web Strap from the Items list and go to Accounting > Matrix Items. In the account used here, NetSuite filled in the parent's option values and name template after the children import; your file doesn't set them. The child list shows Web Strap-1 inch and Web Strap-2 inch with their Width values.

Enlarge

Check the result

1. The parent job reported 1 of 1 records imported, and the children job 2 of 2.
2. Web Strap has the Matrix tag.
3. Width on the parent shows 1 inch and 2 inch.
4. The child list shows Web Strap-1 inch and Web Strap-2 inch.

An import only adds items here. It does not change the option values, parent or matrix type of a child that already exists, so create a replacement child if one of those is wrong.

Common questions

How do I import a matrix item and its child items from a CSV in NetSuite?

Import the parent row first, with Matrix Type Parent Matrix Item. Then import the child rows with Matrix Type Child Matrix Item, Subitem Of set to the parent's internal ID (reference type Internal ID on the mapping), and a Matrix Option column for each option.

Why does my matrix child import fail with Invalid parent reference key?

Subitem of is a reference field, and the mapping's reference type decides how the value is read. In the account used for this guide, a parent name failed even for a parent that existed, and a combined file with the parent row failed because the parent did not exist yet when the children were read. Import the parent first and use its internal ID with reference type Internal ID.

What do I put in Subitem Of for a matrix child item?

The parent's internal ID, with the Subitem of mapping set to Internal ID. External ID is another reference type NetSuite offers; it wasn't tested here.

How do I map a matrix option column?

Head the column Matrix Option - followed by the field name, for example Matrix Option - Width. NetSuite maps it to the matching Item : Matrix Option field. The value must be one of the values in the option's custom list.

Do I import the parent and children in the same file?

NetSuite's guidance describes a combined file with the parent row first. In the account used here it created only the parent and failed every child, so two imports was the path that worked. Try the combined file in your account if you want one run, and fall back to two imports if the children fail.

Do children inherit the parent's accounts and tax schedule?

Not the accounts: the parent's Asset, COGS and Income Accounts are not copied to children during an import. Put the required item fields, such as the accounts and, where your tax setup requires it, Tax Schedule, on every row.