Disclosure: NetSuiteForge may earn a commission through affiliate links in this article. We only recommend solutions we've personally implemented for ecommerce clients. Our editorial process is independent, and our recommendations are based on hands-on experience.

NetSuite CSV Import Best Practices

CSV imports are the duct tape of NetSuite administration. When your integration is down, when you need to mass-update item prices, when you're migrating historical data, or when you need to load 10,000 customer records from an acquired business—CSV import is the tool you reach for.

The problem is that CSV imports in NetSuite are deceptively simple. Upload a file, map some fields, click import—easy, right? Until your import fails at row 4,387 with a cryptic error, you realize you've created 4,386 duplicate records, and your afternoon is gone.

After managing hundreds of CSV imports for ecommerce brands—from initial data migrations to weekly inventory updates—I've developed a systematic approach that prevents the common disasters. This guide covers field mapping, data formatting, error handling, and strategies for large file imports specific to ecommerce operations.

Key Takeaways

• CSV import is NetSuite's native bulk data tool for creating, updating, or deleting records without API development
• Data preparation takes 80% of the time—formatting dates, mapping IDs, cleaning special characters—but prevents 90% of import errors
• Always run a test import with 5-10 rows first before importing the full file to catch mapping and formatting issues early
• For files over 5,000 rows, break into smaller batches and use the queue feature to process asynchronously
• The most common ecommerce import errors are duplicate records, date formatting mismatches, and missing required fields

How Does the NetSuite CSV Import Process Work?

Accessing the Import Tool

Navigate to Setup → Import/Export → Import CSV Records

The import wizard has five steps:

1. Select Import Type: Choose the record type (Item, Customer, Transaction, etc.) and the operation (Add, Update, Add/Update)
2. Upload File: Upload your CSV file
3. Field Mapping: Map your CSV columns to NetSuite fields
4. Save Import Map: Save the mapping for future imports (highly recommended)
5. Run Import: Execute the import with optional scheduling

Import Operations

Add: Creates new records. Fails if a record with the same external ID/key already exists.

Update: Updates existing records. Requires a matching key (internal ID, external ID, or unique field value). Fails if the record doesn't exist.

Add/Update (Upsert): Creates new records or updates existing ones based on the matching key. Most flexible and generally recommended for ongoing imports.

The Matching Key

For updates and upserts, NetSuite needs to know which existing record to match:

• Internal ID: NetSuite's auto-generated unique identifier. Most reliable but requires you to know the IDs.
• External ID: A custom identifier you assign. Best for integrations—set it once, use it forever.
• Name/Number: Match by item name, customer name, or transaction number. Less reliable due to potential duplicates.

Best practice for ecommerce: Use external IDs that match your source system's identifiers. If your Shopify product ID is "7654321," use that as the external ID in NetSuite. This creates a permanent, reliable link between systems.

How Do You Format Data for NetSuite CSV Imports?

Date Formatting

NetSuite's default date format depends on your account's locale settings. The most common formats:

Locale	Date Format	Example
US	MM/DD/YYYY	03/22/2026
UK/EU	DD/MM/YYYY	22/03/2026
ISO	YYYY-MM-DD	2026-03-22

Check your account's date format: Setup → Company → General Preferences → Date Format

Critical gotcha: If your CSV has dates in the wrong format, NetSuite silently misinterprets them. "03/05/2026" could be March 5 or May 3 depending on the format. The import won't error—it just imports the wrong date. Always verify with test rows.

DateTime format: For scheduled dates and timestamps, use "MM/DD/YYYY HH:MM AM/PM" (e.g., "03/22/2026 2:30 PM").

Number Formatting

• No thousand separators: Use "1234.56" not "1,234.56" (commas in CSV files break column parsing)
• Decimal point: Use period for decimal separator
• Currency values: No currency symbols—use "29.99" not "$29.99"
• Negative numbers: Use "-100.00" not "(100.00)"
• Quantities: Integer or decimal depending on item configuration—"5" or "5.00"

Text Fields and Special Characters

• Commas in text: Enclose the field in double quotes: "Widget, Large Size"
• Double quotes in text: Escape with double-double quotes: "He said ""hello"""
• Line breaks in text: Enclose in double quotes. Some fields support HTML line breaks: <br>
• UTF-8 encoding: Save your CSV as UTF-8 to preserve special characters (accented characters, symbols)
• Leading zeros: To preserve leading zeros in fields like zip codes, format the column as text in Excel before saving as CSV

Boolean Fields

NetSuite boolean fields accept:

• "T" or "F" (most reliable)
• "TRUE" or "FALSE"
• "Yes" or "No"
• "1" or "0"

Recommendation: Always use "T" and "F" for consistency.

Dropdown/Select Fields

For dropdown fields, you can use either the text value or the internal ID:

• Text value: Must match exactly (case-sensitive): "Fulfilled" not "fulfilled"
• Internal ID: More reliable—use the number: "3" instead of "Fulfilled"

To find internal IDs for dropdown values: navigate to the list (e.g., Customization → Lists → Custom Lists), click on the list, and note the internal IDs of each value.

Multi-Select Fields

Separate multiple values with the pipe character (|):

"Electronics|Home & Garden|Sports"

Or with pipe and no spaces for internal IDs:

"1|5|12"

Reference Fields (Foreign Keys)

When a field references another record (like category_id references a category), you can use:

• Internal ID: The numeric ID: "142"
• External ID: Your external identifier: "shopify-cat-7654"
• Name/Number: The display name: "Electronics" (less reliable)

Specify in the field mapping which identifier type you're using.

What Are the Most Common Ecommerce Import Scenarios?

Scenario 1: Item/Product Import

The most common ecommerce import. Upload your product catalog:

Required fields:

• Item Name/Number (your SKU)
• Display Name (product title)
• Item Type (Inventory Item, Non-Inventory Item, Kit, etc.)
• Base Price

Recommended fields:

• Description
• Purchase Price (cost)
• Vendor
• Category
• Weight
• UPC/Barcode
• Tax Schedule
• Preferred Stock Level
• Reorder Point

Ecommerce-specific fields:

• Web Store display flag
• URL component (for SuiteCommerce)
• SEO meta title and description
• Feature/bullet point fields

Common issues:

• Duplicate SKUs (use upsert to handle gracefully)
• Items with variants (parent/child structure requires two imports—parent items first, then child items referencing the parent)
• Missing item types (each item type has different required fields)

Scenario 2: Customer Import

Loading customer data from Shopify, Amazon, or a CRM:

Required fields:

• Customer Name (or First Name + Last Name for individual)
• Email (unique identifier for DTC)
• Subsidiary (for OneWorld accounts)

Recommended fields:

• Phone
• Default billing address
• Default shipping address
• Sales Rep
• Category
• Terms
• Price Level

Address handling: Customer addresses in CSV imports require either:

• Flattened address fields (Address Line 1, City, State, Zip, Country) in the main CSV
• A separate address sublist CSV imported as a second pass

Ecommerce tip: When importing Shopify customers, use the Shopify customer ID as the external ID. This makes future syncs and updates reliable.

Scenario 3: Transaction Import (Sales Orders, Invoices)

Transaction imports are the most complex because they have header-level and line-level data.

Header-level fields: Transaction number, customer, date, status, shipping method, payment terms Line-level fields: Item, quantity, rate, amount, tax code

CSV structure for transactions:

External ID, Customer, Date, Item, Quantity, Rate
SO-001, Acme Corp, 03/22/2026, Widget-A, 10, 29.99
SO-001, , , Widget-B, 5, 49.99
SO-002, Beta Inc, 03/22/2026, Widget-C, 20, 19.99

Note: The second line of SO-001 has empty header fields because it's a continuation of the same transaction (a second line item). Only the first row of each transaction should have header values.

Scenario 4: Inventory Adjustment Import

Updating inventory quantities after a physical count:

Required fields:

• Item
• Location
• Adjust Quantity By (positive to add, negative to subtract)
• OR New Quantity (absolute value)

Best practice: Import as inventory adjustments, not direct quantity overrides. This creates an audit trail and properly adjusts inventory valuation.

Scenario 5: Price Update Import

Mass-updating product prices:

Required fields:

• Item (Internal ID or External ID)
• Price Level (which price to update—Base Price, Online Price, Wholesale, etc.)
• Price

Ecommerce tip: Create a saved search that exports your current prices before importing new ones. This gives you a rollback file if the price update has errors.

How Do You Handle Large File Imports?

The 10,000-Row Challenge

NetSuite recommends imports under 10,000 rows for interactive processing. Larger files should be processed asynchronously.

For files under 5,000 rows:

• Import directly (interactive mode)
• Processing takes 2-15 minutes depending on record type and script triggers

For files 5,000-25,000 rows:

• Use the Queue option to process asynchronously
• Break into batches of 5,000 rows
• Schedule imports sequentially (don't overlap)

For files over 25,000 rows:

• Break into multiple CSV files of 5,000 rows each
• Queue each batch with a delay between them
• Monitor the import queue: Setup → Import/Export → View CSV Import Status

Why Smaller Batches Are Better

1. Error isolation: If a batch fails at row 3,000, only that batch is affected, not your entire 50,000-row import
2. Performance: Smaller batches process faster and don't compete with interactive users
3. Retry efficiency: Re-importing 5,000 rows after fixing an error is faster than re-importing 50,000
4. Memory management: Very large imports can hit memory limits and fail entirely

Scheduling Imports for Off-Hours

Navigate to Setup → Import/Export → Saved CSV Imports to schedule recurring imports:

1. Save your import mapping
2. Upload the CSV to the File Cabinet
3. Schedule the import (time, frequency)
4. Set the source to "File Cabinet" and select the uploaded file

For ecommerce: Schedule large imports (inventory updates, price changes) for midnight-6am when user activity is lowest.

How Do You Handle Import Errors?

The Error File

When an import completes (with or without errors), NetSuite provides a summary:

• Records processed: Total rows attempted
• Records imported: Successfully created/updated
• Records failed: Errors encountered
• Error file: Download CSV showing failed rows with error messages

Common Import Errors and Fixes

Error: "You have entered an Invalid Field Value [fieldname]"

• The value doesn't match the expected format or valid options
• Fix: Check the field type. For dropdowns, use exact text or internal ID

Error: "This record already exists"

• You're trying to add a record that matches an existing unique key
• Fix: Use "Update" or "Add/Update" mode instead of "Add"

Error: "Please enter value(s) for [fieldname]"

• A required field is missing
• Fix: Add the missing column to your CSV, or set a default value in the import mapping

Error: "Invalid reference [fieldname]"

• A reference field points to a record that doesn't exist
• Fix: Verify the referenced record exists. Check if you're using the correct ID type

Error: "You cannot delete this record because other records depend on it"

• Trying to update or delete a record that has dependent transactions
• Fix: Review dependencies and handle them first

Import Recovery Process

When a large import partially fails:

1. Download the error file
2. Analyze the error patterns (usually a few common errors across many rows)
3. Fix the data in the error file
4. Re-import only the failed rows (the error file conveniently contains just the failed rows)
5. Repeat until all rows are processed

What Are the Best Practices for Ecommerce CSV Imports?

Practice 1: Always Test with 5-10 Rows

Before importing your full file:

1. Create a test CSV with the first 5-10 rows
2. Import as "Add" to create test records
3. Verify the records in NetSuite (check all fields, especially dates and references)
4. Delete the test records
5. Import the full file

Practice 2: Use External IDs Consistently

Assign external IDs to every record you import:

• Items: Use your SKU
• Customers: Use your Shopify/Amazon customer ID
• Transactions: Use your source system's order number

This makes future updates reliable and avoids duplicate creation.

Practice 3: Save Import Maps

Save every import mapping for reuse:

• Name the map descriptively: "Weekly Inventory Update - Warehouse A"
• Include the date format and file structure in the map name or notes
• Reuse saved maps for recurring imports to ensure consistency

Practice 4: Document Your Import Process

Create a runbook for each recurring import:

1. Source system and export process
2. Any data transformation steps (Excel formulas, scripts)
3. CSV formatting requirements
4. Import mapping and options
5. Validation steps after import
6. Rollback procedure if something goes wrong

Practice 5: Import Related Records in Order

When importing related records, order matters:

1. First: Parent/reference records (categories, vendors, customers)
2. Second: Items (referencing the categories/vendors from step 1)
3. Third: Transactions (referencing the items and customers from steps 1-2)

If you try to import a sales order that references a customer that hasn't been imported yet, it will fail.

Practice 6: Handle Custom Fields Carefully

Custom field internal IDs are in the format "custbody_fieldname" (for body-level) or "custcol_fieldname" (for column-level). Find the exact internal ID:

1. Navigate to Customization → Lists → Custom Fields
2. Find your custom field
3. Note the "ID" column value
4. Use that exact ID in your CSV header or field mapping

Practice 7: Pre-Validate with a Spreadsheet

Before importing, validate your data in Excel/Google Sheets:

• Check for blank required fields
• Verify date formats are consistent
• Look for duplicate keys
• Ensure reference IDs exist (cross-reference with a NetSuite export)
• Check for leading/trailing whitespace in text fields
• Verify number formatting (no commas, correct decimal places)

Frequently Asked Questions

Can I import into custom record types?

Yes. When selecting the import type, choose "Custom Records" and then select your specific custom record type. The field mapping works the same as standard records.

Can I undo a CSV import?

There's no automatic "undo" button. For small imports, manually delete the created records. For large imports, you'll need a mass delete (via CSV import with "Delete" operation) or a script. This is why test imports and rollback planning are critical.

How do I import records with sublists (like addresses or line items)?

Sublists require special handling:

• Inline sublists (like transaction line items): Include in the same CSV with repeated header rows for each transaction
• Separate sublists (like addresses): Often require a second import step using the parent record's internal ID as a reference

Can I schedule recurring CSV imports?

Yes. Save the import mapping, upload the CSV to the File Cabinet, and schedule the import under Setup → Import/Export → Saved CSV Imports. For truly automated recurring imports, use SuiteScript's N/file module to read files from the File Cabinet.

What's the maximum CSV file size?

NetSuite supports CSV files up to about 10 MB. For larger files, split them into smaller batches. The practical limit depends more on row count and processing time than file size.

Can I import to update specific fields without affecting other fields?

Yes. When using "Update" mode, only the fields you include in the CSV are modified. Fields not in the CSV are left unchanged. This lets you update prices without affecting descriptions, for example.

Ready to Master NetSuite Data Management?

CSV imports are an essential skill for NetSuite administrators. Whether you're migrating data from a previous system, performing weekly inventory updates, or mass-updating product information, a disciplined import process prevents errors and saves hours of cleanup work.

Start with the basics—proper formatting, test imports, external IDs—and you'll avoid 90% of the problems that plague CSV imports. Build documented, repeatable processes for your recurring imports, and what used to be a stressful afternoon becomes a routine 15-minute task.

Take our free NetSuite readiness assessment → to evaluate your data management processes and get recommendations for import automation that will save your team hours every week.