Key Takeaways
- NetSuite Offers Three Import Methods: The CSV Import Assistant for manual bulk imports, SuiteScript for automated and programmatic imports, and Web Services (SuiteTalk REST/SOAP) for system-to-system integrations. Each fits a different use case.
- Record Dependencies Control Import Order: Customer records must exist before you import transactions. Item records must exist before you import order lines. Importing in the wrong sequence breaks foreign key references and creates failed records that are difficult to clean up.
- Data Scrubbing Before Import Is Not Optional: NetSuite recommends that you scrub your data before importing it. Duplicate records, mismatched date formats, and missing required fields will cause import failures that require manual correction record by record.
- Always Test in Sandbox First: Run every import against a sandbox account before touching production. A failed import in a sandbox costs you an hour. A failed import in production can cost days of cleanup.
- Character Encoding Causes More Failures Than Most Teams Expect: NetSuite expects UTF-8 encoding by default. Files saved in Windows-1252 or Latin-1 encoding commonly produce import errors on special characters, international names, and currency symbols.
- SuiteScript Automates Recurring Imports: If you import the same record type regularly (nightly price updates, weekly inventory adjustments), a Scheduled Script using the task.CsvImportTask API runs the import automatically on a schedule without manual intervention.
What is the fastest way to get a large amount of data into NetSuite without typing it in record by record?
That question comes up in two situations. The first is a migration from a legacy system, where you have years of customer, vendor, item, and transaction data that needs to move into NetSuite before go-live. The second is ongoing operations, where you regularly import data from external sources: price lists from suppliers, inventory adjustments from a warehouse system, or sales orders from an ecommerce platform.
NetSuite handles both situations, but the right method differs. This guide covers all three import methods, the record dependency order that determines whether your import succeeds or fails, how to prepare your data correctly, and how to automate imports that repeat on a schedule.
The Three NetSuite Import Methods
CSV import is the most commonly used method for transferring small to medium-sized data sets from other applications into NetSuite. The CSV import process saves time and prevents errors by submitting data in a CSV file. This data can add or update many records at one time, avoiding the need for manual data entry.
But CSV import through the Import Assistant is not the only option. The right choice depends on your volume, technical capability, and whether the import is a one-time event or a recurring process.
Method 1: The CSV Import Assistant
The Import Assistant is a step-by-step wizard inside NetSuite. It walks you through uploading a CSV file, selecting the record type, mapping your columns to NetSuite fields, and running the import.
Navigate to: Setup > Import/Export > Import CSV Records
You need the Import CSV File permission to access this. The types of records you can import depend on your assigned role and which features are enabled in your account.
The Import Assistant covers most common record types: customers, vendors, contacts, items, transactions, journal entries, and custom records. A small number of imports (vendor price lists, bulk order fulfillment, employee commission data) use template-based imports that are separate from the main Import Assistant.
Method 2: SuiteScript (task.CsvImportTask)
After you have saved an import map in the Import Assistant, you can use a SuiteScript API to run that same import programmatically. The task.CsvImportTask API takes a saved CSV import configuration and a data file, submits the import job, and runs it in the background.
This is the right approach for recurring imports. Instead of a team member logging in and manually uploading a file every day, a Scheduled Script fetches the file from a set location and submits it automatically.
For a full explanation of how SuiteScript works and which script types handle different automation needs, this blog explains what SuiteScript is and how its ten script types work in practical terms.
Method 3: SuiteTalk Web Services (REST and SOAP)
SuiteTalk is NetSuite’s native web services API. External systems can send records to NetSuite in real time using REST or SOAP calls, without going through a CSV file at all. This is the right method when data needs to flow between systems continuously rather than in batches.
For example, an ecommerce platform that creates orders can push each order to NetSuite as a sales order the moment it is placed. No CSV, no manual upload, no scheduled import. The integration handles it record by record in real time.
For businesses that need to connect external systems to NetSuite through APIs or integration platforms, the approach to NetSuite integration services covers the architecture decisions and connection options in detail.
The Record Dependency Import Sequence
This is the section most import guides skip, and it is the reason most data migrations run into problems.
NetSuite records reference each other. A customer transaction references a customer record. An order line references an item record. A contact references a company. If you import a transaction before the customer it belongs to exists in NetSuite, the import fails with a reference error.
The correct import sequence for a full data migration is:
Tier 1: Reference Data (import these first)
- Chart of accounts
- Subsidiaries and locations
- Currencies and exchange rates
- Tax codes and tax groups
- Payment terms
- Price levels
Tier 2: Master Records (import after Tier 1 is complete)
- Vendors
- Customers
- Items and inventory
- Employees
- Contacts (require customer or vendor records to exist first)
Tier 3: Transactions (import after Tier 1 and Tier 2 are complete)
- Purchase orders
- Sales orders
- Invoices and bills
- Journal entries
- Inventory adjustments
Tier 4: Historical Data (import last)
- Open balances
- Historical transactions for reporting
- Previous payment records
Skipping this sequence is the most common cause of failed migrations. A sales order import that runs before customers are fully loaded will produce import errors for every order belonging to a customer whose record does not yet exist.
For teams planning a full data migration from a legacy ERP to NetSuite, the NetSuite migration services page covers how Folio3 handles the sequencing, data scrubbing, and validation steps for complex migrations.
How to Run a CSV Import: Step by Step
Step 1: Prepare and Scrub Your Data
Before opening the Import Assistant, prepare your CSV file:
- Remove duplicates. NetSuite will create a new record for every row in your file unless you specify an identifier for updates. Duplicate rows create duplicate records.
- Format dates consistently. NetSuite expects dates in MM/DD/YYYY format by default. Mixed date formats in your file will cause some rows to fail.
- Check required fields. Every record type has required fields. An item import that is missing the item name or item type for any row will fail those rows. Review the NetSuite documentation for your record type before building the file.
- Set encoding to UTF-8. Save your CSV file in UTF-8 encoding, not Windows-1252 or Latin-1. Files with the wrong encoding produce errors on any row containing special characters, accented letters, or currency symbols.
- Clean up reference values. If your CSV references another record by name (a customer name, a vendor name, a GL account name), the value in your CSV must exactly match the name as it appears in NetSuite. Case sensitivity and spacing differences cause lookup failures.
Step 2: Navigate to the Import Assistant
Go to Setup > Import/Export > Import CSV Records.
On the first screen, select your Import Type (the category of record: Transactions, Lists, Support, etc.) and your Record Type (the specific record within that category: Sales Order, Customer, Inventory Item, etc.).
Upload your CSV file and select the character encoding that matches your file. UTF-8 is the default recommendation.
Step 3: Set Import Options
On the Import Options screen, set your Data Handling:
- Add: Creates new records from every row. Use this for initial imports.
- Update: Updates existing records. Every row must include an identifier (Internal ID, External ID, or a name field) that matches an existing record.
- Add or Update: Tries to match existing records and updates them if found, creates new ones if not. Use when your file is a mix of new and existing records.
In the Advanced Options, decide whether to enable Run Server SuiteScript and Trigger Workflows. Enabling this fires any User Event Scripts and workflows attached to the records being imported. Disable it for faster imports when you do not need those to run, or when you want to avoid triggering emails or downstream automations during a bulk load.
Step 4: Map Your Fields
The field mapping screen shows your CSV column headers on the left and NetSuite record fields on the right. Drag and drop to connect each CSV column to the correct NetSuite field.
Pay attention to required fields (marked with an asterisk). Every required field must be mapped. Optional fields can be left unmapped if your CSV does not contain that data.
Click the pencil icon next to any field mapping to configure how NetSuite interprets the values in that column: as an Internal ID reference, an External ID reference, or a display name lookup.
Save your mapping with a descriptive name. Saved mappings can be reused for future imports of the same record type.
Step 5: Test in Sandbox, Then Run in Production
Before running the import in your live NetSuite account, run the exact same file in your sandbox. Review the import results for errors. Open a few records to confirm the data populated correctly. Check that reference fields resolved to the right records.
If the sandbox import produces errors, fix the source file and re-run. Do not move to production until the sandbox import completes cleanly.
When ready, run the same process in your production account. After the import completes, review the import log for any rows that failed. Failed rows are listed with error reasons. Correct those rows individually or in a separate follow-up import file.
Common CSV Import Errors and How to Fix Them
“Record not found” on a Reference Field
Your CSV references a record that does not exist in NetSuite. This happens when you map a column to a field that expects an Internal ID or a name that should match an existing record, but the value in your file does not match anything in NetSuite.
Fix: Check the exact spelling and formatting of the reference value in your NetSuite account. For customer references, the format is often Parent Company : Child Company. Update your CSV to match.
Date Format Errors
Rows fail because the date values in your file do not match NetSuite’s expected format.
Fix: Open your CSV file and confirm all date columns use MM/DD/YYYY format. If your source data exports in a different format, reformat the column in Excel or Google Sheets before importing.
Encoding Errors on Specific Characters
Certain rows fail or import corrupted text because of encoding mismatches.
Fix: Resave your CSV file explicitly in UTF-8 encoding. In Excel, use Save As > CSV UTF-8 (Comma delimited). In Google Sheets, download as CSV (the default is UTF-8).
Missing Required Field Errors
Rows fail because a required field is empty in your CSV.
Fix: Check which fields are required for your record type using the NetSuite documentation or by looking at the required fields when creating a record manually in NetSuite. Add that column to your CSV and populate it for every row.
Automating Recurring Imports With SuiteScript
For imports that happen on a schedule, the manual CSV Import Assistant adds extra work. A team member has to prepare the file, navigate to the wizard, upload it, and monitor the results every time.
SuiteScript’s task.CsvImportTask API replaces that manual process. Here is how it works:
- Create and save an import mapping in the Import Assistant (a one-time setup step)
- Write a Scheduled Script that retrieves the data file from a configured location (a file cabinet folder, an SFTP path, or an external API)
- Use task.create({ taskType: task.TaskType.CSV_IMPORT }) to build the import task, attach the saved mapping and the file, and submit it
- The script runs on the configured schedule without any manual intervention
This approach is used for nightly price list updates from suppliers, daily inventory sync from warehouse systems, and weekly payroll data imports from HR platforms.
For developers wanting to understand how SuiteScript handles bulk record operations and integrations beyond CSV imports, this blog covers SuiteScript for custom business processes with practical automation examples. For a deeper look at SuiteScript’s automation capabilities including scheduling, map/reduce for large datasets, and governance management, this in-depth guide covers automation and customization using SuiteScript’s top-requested features.
Exporting Data From NetSuite for Reference
When building import files for updates, you often need to export existing NetSuite data first to get the Internal IDs that your update file needs to reference. The most efficient way to do this is through a saved search export.
Run a saved search for the record type you are updating, add the Internal ID as a column, and export the results to CSV. Use that exported file as the basis for your update import file. This approach removes the guesswork on Internal IDs and prevents reference mismatches.
For guidance on how to export data from NetSuite using saved searches and how to create export-ready CSV files through SuiteScript, this blog on creating CSV files from NetSuite saved search results covers the export side of the import/export workflow.
Final Thoughts
Data import in NetSuite is not complicated when the process is followed correctly. The mistakes that turn a two-hour import into a two-day cleanup almost always come from the same places: importing out of sequence, skipping the sandbox test, mismatched encoding, or missing required fields in the source file.
Get the sequence right. Scrub the data before you import. Test in sandbox. Run the production import. Check the log.
For businesses handling a full data migration from a legacy system into NetSuite, the sequencing, scrubbing, and validation work involved is where a partner with experience pays for itself. The NetSuite implementation services page covers how Folio3 approaches go-live data migration for businesses at every stage of complexity.
FAQs
What is the NetSuite Import Assistant?
The NetSuite Import Assistant is a step-by-step wizard for importing data from CSV files into NetSuite records. It is accessed at Setup > Import/Export > Import CSV Records. It handles most record types including customers, vendors, items, transactions, and custom records. You need the Import CSV File permission to use it, and the available record types depend on your role and the features enabled in your account.
What is the correct order to import data into NetSuite?
Import reference data first (chart of accounts, subsidiaries, currencies, tax codes, payment terms). Then import master records (vendors, customers, items, employees). Then import transactions (purchase orders, sales orders, invoices, bills). Then import historical data. Each tier depends on the previous tier’s records existing. Importing out of sequence produces reference errors.
What file format does NetSuite accept for imports?
NetSuite’s Import Assistant accepts CSV (comma-separated values) files. The file must be saved in UTF-8 character encoding for best results. Excel files must be saved as CSV before importing. Avoid Windows-1252 or Latin-1 encoding, as these produce character encoding errors on rows with special characters.
Can I automate CSV imports in NetSuite?
Yes. After saving an import mapping in the Import Assistant, you can automate the import using SuiteScript’s task.CsvImportTask API in a Scheduled Script. The script retrieves the data file on a schedule and submits the import job automatically. This replaces the manual upload process for recurring imports.
What should I do if some rows in my import fail?
After an import completes, review the import log for failed rows. Each failure includes an error reason. Common causes are reference field mismatches (the value in your CSV does not match an existing NetSuite record), missing required fields, and date format mismatches. Fix the failing rows in a separate CSV file and run a follow-up import to load the corrected records.
Should I test imports in sandbox before production?
Always. Run every import in your NetSuite sandbox account first. Verify that records are created correctly, that reference fields resolve to the right records, and that the data looks accurate before running the same process in production. A failed sandbox import costs an hour of your time. A failed production import can require days of cleanup.
