Data migration is the workstream that most often decides whether a NetSuite go-live feels controlled or chaotic, and it’s the one companies plan least. Configuration gets workshops. Training gets a schedule. Migration gets a line on the project plan that says “load data” and an assumption that the export from the old system will be usable.
It won’t be. Every migration we’ve run has revealed duplicate customers, retired items still marked active, addresses in the wrong fields, and balances nobody can explain. The good news is that the process for handling all of this is well understood, and NetSuite’s own documentation is specific about how loading works. Here’s the playbook.
Step 1: Decide What Actually Moves
The first decision is scope, and “everything” is almost always the wrong answer.
Master data always moves: the chart of accounts, subsidiaries and segments (classes, departments, locations), items, customers, vendors, employees, and their contacts and addresses. This is the foundation every transaction references.
Open transactions almost always move: unpaid customer invoices, unpaid vendor bills, open sales orders, open purchase orders, and current inventory quantities and costs. These represent the live state of the business on cutover day.
Closed historical transactions are the judgment call. There are three common approaches. The leanest brings opening balances only: a trial balance as of the cutover date, posted through journal entries, with historical detail staying in a read-only copy of the legacy system. The middle path adds one or two years of transaction detail so that reporting, customer history, and item sales history exist in NetSuite from day one. The heaviest migrates everything, which sounds appealing and rarely survives contact with the effort estimate, because old transactions have to be mapped to a new chart of accounts and item structure that didn’t exist when they were entered.
Most small and mid-sized companies land on opening balances plus open items plus a defined slice of history, with the old system kept read-only for lookups. Decide this in discovery, in writing, because it drives the entire migration workload.
Step 2: Respect the Dependency Order
NetSuite records reference each other, so imports have to run in an order that satisfies those references. Load a sales order before its customer exists and the import fails. The reliable sequence:
Chart of accounts and accounting setup first, then subsidiaries and segments. Items next, since transactions and inventory reference them. Then customers and vendors, and in OneWorld accounts Oracle’s documentation notes that the Subsidiary field is required for these entity imports, so the source file has to carry it. Contacts and additional addresses follow their parent records. Open transactions come after every master record they touch. Inventory quantities and costs load through inventory adjustments or worksheets against the item and location records already in place. Opening balances post last, through journal entries, once everything else is reconciled.
Write the sequence down as a runbook with owners and checkpoints. You’ll run it more than once.
Step 3: Clean Before You Load
Cleanup is the client’s job, and it’s the biggest time sink in the project. The work is unglamorous: merge duplicate customers, retire dead SKUs, standardize naming, fill required fields, fix email and address formats, and decide what to do with the 400 records that have no clear owner.
Two NetSuite-specific practices make loading dramatically more reliable. First, assign an External ID to every record in your source files. Oracle’s guidance is that External ID or Internal ID references are preferable to name references, because a name reference has to match a dropdown value exactly, character for character, while an ID reference doesn’t care about spelling. External IDs also make updates and re-loads repeatable. Second, build your templates from NetSuite itself: exporting the relevant record list view, even an empty one, gives you column headers that map cleanly in the Import Assistant.
Step 4: Know Your Loading Tools and Their Limits
For most migrations the workhorse is the CSV Import Assistant, found under Setup > Import/Export > Import Tasks > Import CSV Records. It runs through five steps: scan and upload, import options, file mapping (for multi-file imports), field mapping, and start import.
The limits matter for planning. Oracle documents a ceiling of 25,000 records or 50 MB per import job, and for multi-file uploads the combined files must stay under those limits. A 90,000-row item file is four import jobs, and Oracle recommends breaking large loads into smaller batches for performance anyway. Multi-file imports let you attach linked files for sublist data, such as multiple addresses per customer, with the main record data required to be in the primary file.
Two options deserve caution. The Import Assistant lets you save an import map, which is essential: a saved map turns a painful mapping session into a repeatable job for the next mock load. And the Overwrite Missing Fields setting, if enabled on an update import, will blank out existing NetSuite fields wherever the CSV cell is empty. More than one migration has wiped good data with a well-intentioned update.
When volumes or complexity outgrow the assistant, there are two escalations. SuiteScript’s CsvImportTask can run saved import maps on a schedule or from a script, which is useful for chunked loads, though Oracle notes scripted imports are subject to the same 25,000-record limit. Beyond that, SuiteTalk web services (REST or SOAP) or an integration platform can push data at volume with custom transformation logic. These paths are where experienced NetSuite developers earn their place on a migration team: a scripted load with validation and error logging beats a person babysitting 40 CSV jobs, and for complex custom records it’s often the only practical route.
Step 5: Run the Mock-Cutover Loop
No migration is right the first time, and the process should assume that. Load into Sandbox, then reconcile: AR aging in NetSuite against AR aging in the legacy system, AP aging the same way, inventory quantity and value by location, and the trial balance to the penny. Every variance gets explained and fixed in the source files or the mapping, then you reload.
Plan for at least two full mock cutovers, ideally three, with the last one run as a dress rehearsal on the actual cutover timeline. The goal is that the real cutover weekend is a repeat of something the team has already done successfully, with a known duration and a known reconciliation result.
Step 6: Cut Over
On the real cutover, freeze entry in the legacy system, extract final data, run the runbook, reconcile, and get sign-off from finance before anyone transacts in production. Time it at a period boundary, ideally the start of a month, so opening balances are clean. Keep the legacy system read-only and accessible for lookups; you’ll want it for months.
Then expect a tail. The first month-end close will surface a handful of records that migrated with wrong dates, missing segments, or a subsidiary mix-up. That’s normal. What’s not normal is discovering a migration problem at year end, which is what happens when the reconciliation in step 5 was skipped.
A Realistic Timeline
Migration runs in parallel with configuration rather than after it, and it usually spans the middle two-thirds of the project. Cleanup should start in the first two weeks, because it’s the long pole and it depends on people who have day jobs. The first mock load typically lands six to eight weeks before go-live, the second three to four weeks out, and the dress rehearsal a week or so before cutover, with reconciliation results reviewed after each. Compressing that sequence is how migration becomes the reason a go-live date moves. If the first mock load is happening two weeks before go-live, the date is already at risk, whatever the status report says.
Who Owns What
Migration works when ownership is explicit. The client owns data quality and the business decisions about scope and history. The implementation partner owns mapping, tooling, load execution, and the reconciliation method. When you’re evaluating NetSuite implementation partners, ask specifically how many mock loads are included in the quote, who performs cleanup, how they handle records that fail validation, and what the reconciliation deliverable looks like. Vague answers on migration are the leading indicator of a rough go-live.
Handled this way, data migration is a repeatable process with a runbook, a reconciliation, and a rehearsal, and the business starts life on NetSuite trusting its numbers from the first day.
