# How to Import CSV Data Into NetSuite Reliably > Source: https://netray.co/erp-help/netsuite-how-to-csv-import-tips > Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems. > Section: ERP Help ## Short answer NetSuite's CSV Import Assistant, under Setup > Import/Export > Import CSV Records, maps spreadsheet columns to record fields, matches existing records by internal ID or a chosen field, and can create, update, or upsert in a single run. The most reliable imports use a saved import map, reference records by internal ID where possible, and stage the file with a header row that exactly matches expected column types. ## Kind how-to ## System netsuite ## Erp Oracle NetSuite ## Module CSV Import / Import Assistant ## Query NetSuite CSV import tips and best practices ## Alternate Queries - how to do CSV import in NetSuite without errors - NetSuite import assistant field mapping - NetSuite CSV import update existing records - NetSuite bulk import journal entries CSV ## Applies To NetSuite CSV Import Assistant, all editions, standard and custom record types ## Steps ### How to run a clean CSV import **Items:** Go to Setup > Import/Export > Import CSV Records and choose the record type (or Custom Record, or Transaction type such as Journal Entry). Select the import behavior: Add (create new only), Update (existing only, matched by a key field), or Add or Update (upsert). For Update or upsert, choose the match field carefully; Internal ID is the most reliable match, external ID or a unique custom field are next best, and Name is the riskiest because names are rarely unique. In the field mapping step, map every required field explicitly; do not rely on NetSuite's auto-match for fields with similar but not identical column headers. For list/record fields (customer, item, subsidiary, location), reference the exact value as it appears in NetSuite, or better, the internal ID in a dedicated column to avoid ambiguous text matches. For transactions with line items (journal entries, sales orders), use the multi-line CSV format where each line item is a separate row sharing the same transaction-level key column, and check Multiple Line Items on the import. Run the import first against a small test batch (5-10 rows) and check Setup > Import/Export > View CSV Import Status for row-level error detail before running the full file. Save the mapping as an Import Map for repeat imports of the same file structure, under the mapping step's Save option. ## Sections ### Choosing the right match field **Body:** Add or Update imports rely on a match field to decide whether a row updates an existing record or creates a new one. Internal ID is unambiguous but requires you to already know NetSuite's internal ID for each row, usually from a prior export. External ID is the best option for integrations feeding data from another system, since you control the value and it is guaranteed unique per record type. Matching on Name or another text field is common for quick one-off imports but breaks silently when two records share a name; NetSuite will either error on ambiguous match or update the wrong record depending on settings, so avoid it for anything touching financial data. ### Multi-line transaction imports **Body:** Journal entries, sales orders, and other transactions with line items import as multiple CSV rows per transaction, where header fields (date, memo, subsidiary) repeat identically on every line and line-specific fields (account, amount, item) vary per row. NetSuite groups rows into one transaction when the header fields match and Multiple Line Items is checked on the import. A common failure is a debit/credit journal entry import where the total does not balance because of a rounding difference or a missing offset line; the import fails the whole transaction with an out-of-balance error rather than partially posting it. **Code:** - External ID,Date,Account,Debit,Credit,Memo JE-1001,1/15/2026,Cash,1000.00,,Jan reclass JE-1001,1/15/2026,AR,,1000.00,Jan reclass ### Handling list, select, and reference fields **Body:** Fields that point to another record (customer, item, employee, class, department, location) match by display value unless you provide an internal ID column instead, which is more reliable when values contain punctuation, are subsidiary-specific, or could collide with another record's name. For custom list/record fields, the CSV value must exactly match the list option's display value including case and spacing; a trailing space or a renamed list value that the file still references by the old text will cause a silent skip or an unmatched-value error on that row. ### Diagnosing failed rows **Body:** Setup > Import/Export > View CSV Import Status shows a per-row status with a downloadable error file listing the exact reason for each failed row, such as a missing required field, an unmatched reference value, or a permission restriction on the record type. Large imports (tens of thousands of rows) queue as background jobs; check status periodically rather than assuming completion, since NetSuite processes CSV imports in batches and a mid-file error does not necessarily stop later rows from processing. ## Pitfalls - Matching Add or Update imports on Name instead of internal ID or external ID, risking updates to the wrong record when names collide. - Leaving list/reference field values as free text that does not exactly match NetSuite's stored display value, causing silent row failures. - Not checking Multiple Line Items on multi-row transaction imports, which causes each CSV row to become a separate single-line transaction instead of one multi-line transaction. - Importing without a small test batch first, then having to clean up hundreds of bad records after a full-file run. - Assuming CSV import respects the same field-level validation and workflow triggers as manual entry; some User Event script logic and workflow actions behave differently or are skipped depending on script deployment context settings. - Ignoring the import log's row-level errors and only checking the summary count, missing partial failures in a large file. ## Ai Angle ERPray, working against your NetSuite account's actual field definitions and list values, can pre-validate a CSV file before you run the import, flagging rows with reference values that will not match, required fields left blank, or journal entry batches that will fail the balance check, catching the errors that normally only surface after the import job finishes. ## Faq ### What is the difference between internal ID and external ID for matching? **Answer:** Internal ID is NetSuite's own auto-assigned numeric identifier, only known after a record exists in NetSuite. External ID is a value you assign, ideal for integrations where the source system's own ID drives repeat imports without needing to look up NetSuite's internal ID first. ### Can CSV import trigger workflows and scripts? **Answer:** It depends on the script or workflow's deployment context settings; a User Event script or workflow set to run only on the User Interface context will not fire during CSV import, while one set to All Contexts or explicitly including CSV Import will. ### How large can a single CSV import file be? **Answer:** NetSuite supports files up to a configured row and size limit that varies by account, typically tens of thousands of rows; very large datasets are usually better split into multiple files or handled via SuiteScript/CSV import via SuiteTalk for more control and error handling. ### Why did my journal entry import fail with an out-of-balance error? **Answer:** All rows sharing the same transaction key (usually external ID) must sum debits equal to credits per subsidiary. A missing offset line, a rounding mismatch, or a currency conversion difference will trip this validation and reject the whole transaction. ## Search terms NetSuite CSV import, NetSuite import assistant, NetSuite CSV field mapping, NetSuite add or update import, NetSuite journal entry CSV import, NetSuite external ID vs internal ID, NetSuite import multiple line items, NetSuite CSV import status errors --- Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json