NetSuite Insights & Guides | CuriousRubik

NetSuite CSV Import Guide with Validation and Recovery

Written by CuriousRubik | May 18, 2018, 1:56:00 PM

Updated 6 October 2026.

A safe NetSuite CSV import has three controls: a defined target population, a reviewed mapping and a reconciliation that proves the intended result. A completed import job tells you the platform processed the submitted data. It does not by itself prove that the correct records, amounts or transaction lines were created or updated.

Use this workflow for planned migrations and controlled bulk maintenance. It deliberately avoids a universal sample file because required fields and supported operations vary by record type and account setup. Start with the current documentation for the actual record you intend to change.

Define the operation and the identifiers

Write down whether the job creates new records, updates existing records or contains an explicitly identified mixture. Choose the corresponding data-handling option after checking the record-specific behavior. Do not switch from add to add-or-update merely to make an error disappear without understanding which existing records might be matched.

Identify every source record with a stable key. Preserve external identifiers through cleansing and document their relationship to NetSuite records. When updating records already in the target account, a verified internal-ID crosswalk may be appropriate. Names and display labels can change or be ambiguous.

Oracle's general CSV conventions favor internal or external ID references and document file-format and size requirements. The current documented limit is 25,000 records or 50 MB per import job, including combined files for multiple-file uploads. Plan smaller controlled batches when that improves diagnosis and reconciliation; the limit is not a recommended batch size for every account.

Clean the file without changing its meaning

Inspect identifiers for leading zeros, dates for locale ambiguity and numbers for decimal or thousands separators. Review the actual saved CSV in a text-aware tool, not only its spreadsheet appearance. Spreadsheet applications can silently change long identifiers, dates or scientific notation.

Give every column a clear header. Validate required fields, reference values and related-record dependencies before upload. Separate absent information from an intentional request to clear a value. Missing-field overwrite options can have material consequences, so review their behavior in the relevant import documentation and test deliberately.

For hierarchical and multi-select fields, confirm the supported delimiter and reference syntax. Do not assume a comma within a value has the same meaning as the file's column delimiter. Retain a clean input version and the rules used to produce it.

Review settings as part of the change

Record the account, role, record type, form, data handling and advanced options. Consider workflows, scripts and validation that may run when records are imported. Any setting that bypasses or changes normal behavior needs an explicit rationale and business approval.

Oracle's CSV overview explains that available imports depend on roles, permissions and enabled features, and that mappings can be saved for reuse. Treat a saved mapping as versioned configuration. Reusing its name does not prove its fields or options still match the file in front of you.

Where multiple files represent related records or sublists, define the join keys and expected relationship counts. Check for orphan lines and duplicated parent keys. A correct total row count cannot reveal whether children have been attached to the wrong parent.

Use the Import Assistant for the approved sample

With the necessary Import CSV File and record permissions, open Setup > Import/Export > Import CSV Records. Menu wording and available record types can vary by role and account.

  1. Scan and upload the reviewed CSV, selecting the correct import type, record type, encoding and delimiter.
  2. Set the approved data-handling and advanced options. Map file relationships for multi-file imports, then map the source fields to the intended NetSuite fields.
  3. Review the saved mapping and run only the approved sample. Check Import Job Status, inspect created or changed records and reconcile successes and failures before expanding the batch.

File Mapping is required only for multi-file imports. A saved mapping does not waive the validation and retry controls below.

Test representative records

Build a small sample that contains the difficult cases: special characters, inactive references, missing optional fields, multiple lines and unusually long identifiers. Include an intentional invalid record so the team understands how errors appear and what information is retained.

Capture the resulting target records, financial effect where relevant and import status. Validate business meaning with the owner. A customer update should preserve unrelated addresses and classifications; a transaction import should retain the approved dates, amounts and references.

Test line updates separately from header updates. Oracle's transaction-line import guidance describes matching and update behaviors that depend on the sublist and options. A rerun can append or otherwise affect lines if it does not match them as intended. Establish the exact behavior for the target transaction instead of assuming updates replace the whole record.

Handle partial failure explicitly

After the full batch, record successful and failed populations separately. Read error details and group them by cause: missing references, invalid values, permissions, business validation or incorrect operation. Correct the cause in the controlled source or mapping rather than editing errors ad hoc without a trace.

Before retrying, determine which records already exist and whether any successful parent records contain incomplete intended detail. Reconcile the retry population against the original batch. A full-file rerun is appropriate only when the tested design proves it will produce the intended result safely.

Do not treat a duplicate error as an invitation to delete the target record. It may identify a valid prior success, a legitimate pre-existing record or a key-design problem. Investigate the relationship first.

Hypothetical recovery example

An administrator imports 120 customer updates. The status shows 112 successful records and eight failures caused by an invalid sales representative reference. The owner confirms the correct reference for those eight records.

The administrator preserves the original file, creates a version containing the verified failed population and reruns only that correction after a sample check. A comparison then confirms that all 120 intended customers have the approved values and that no unintended customers changed. The successful count is evidence of processing; the comparison establishes the business result.

Reconcile and close the job

Keep a reusable closeout checklist:

  • Submitted population equals successful, failed and explicitly excluded records
  • Source keys map to the intended target records
  • Required values and relationships match approved expectations
  • Transaction quantities and amounts reconcile where applicable
  • Unrelated data remains intact on sampled updates
  • Errors and retries have documented dispositions
  • Business owner has accepted the result

Retain the file version, mapping, settings, job reference, error output and reconciliation. Store sensitive exports with appropriate access controls. The next administrator should be able to explain exactly what the import did without relying on someone's memory.

A CSV import becomes dependable through preparation and proof. Establish those controls on the smallest representative sample before scaling up to the complete data set.

Related resources