NetSuite SuiteScript 2.1 Migration: What You Need to Know Before 2028.2

NetSuite has been moving its scripting platform toward SuiteScript 2.1.

The transition affects organizations that still have:

• SuiteScript 1.0 scripts
• SuiteScript 2.0 scripts
• Scripts using @NApiVersion 2.x
• Older customizations and automations that depend on legacy scripting versions

Oracle's current transition timeline is:

1. 2026.2

   SuiteScript 2.1 becomes the standard scripting model

2. 2027.1

   SuiteScript 1.0 enters end-of-life support (critical issues only)

3. 2028.1

   New accounts can no longer deploy SuiteScript 1.0 (existing accounts still can); SuiteScript 2.0/2.x run as 2.1 by default

4. 2028.2

   New and existing scripts must use SuiteScript 2.1

The first question is simple:

Do you have legacy SuiteScript in your NetSuite environment?

If your company has been using NetSuite for several years, especially if the account has been heavily customized, it is worth checking. Look for scripts using:

@NApiVersion 1.0
@NApiVersion 2.0
@NApiVersion 2.x

These are the types of scripts Oracle recommends reviewing as part of the transition to SuiteScript 2.1.

You should also look beyond the script files themselves. A script may be connected to a business process that your finance, sales, procurement, warehouse or operations teams depend on every day.

One common misconception is that SuiteScript migration simply means changing the version number in the script. For SuiteScript 1.0, that is not the case.

SuiteScript 2.1 uses a modular architecture and a different programming model. Legacy SuiteScript 1.0 global functions generally need to be replaced with the appropriate SuiteScript 2.1 modules and methods.

nlapiLoadRecord()
nlapiSearchRecord()
nlapiSubmitRecord()

N/record
N/search
// and their module methods

There is also no guarantee that every SuiteScript 1.0 API has a direct one-to-one replacement.

Oracle's SuiteScript 1.0 to 2.1 API map specifically notes that some SuiteScript 1.0 APIs do not have a SuiteScript 2.1 equivalent. nlapiYieldScript and nlapiSetRecoveryPoint, for example, are usually replaced by redesigning the job as a Map/Reduce script.

That is why a proper SuiteScript 1.0 to 2.1 migration should include code review, dependency analysis and testing rather than a simple find-and-replace exercise.

The situation is different for SuiteScript 2.0. SuiteScript 2.0 and SuiteScript 2.1 share the SuiteScript API, but SuiteScript 2.1 uses a different JavaScript runtime.

This means that a SuiteScript 2.0 script may require less restructuring than a SuiteScript 1.0 script, but it still needs to be tested for compatibility.

Oracle provides account-level preferences, Execute SuiteScript 2.0 Server Scripts as 2.1 and Execute SuiteScript 2.x Server Scripts as 2.1 (under Setup > Company > Preferences > General Preferences), that let eligible 2.0 and 2.x server scripts run in the SuiteScript 2.1 runtime for compatibility testing. After successful testing, the script can be updated to use @NApiVersion 2.1.

A migration assessment should not focus only on one type of script. Depending on your account, you may need to review:

User Event Scripts

Can affect transactions and records when users create, edit, delete or submit data.

Client Scripts

Can control behaviour on NetSuite forms and influence the user experience.

Suitelets

Custom Suitelets may provide internal applications, dashboards, forms or business processes.

RESTlets

Particularly important when NetSuite is connected to external applications or integrations.

Scheduled Scripts

Scheduled automation may be responsible for important background processes.

Map/Reduce Scripts

Can support large-volume data processing and complex automated jobs.

Workflow Action Scripts

Some business processes may rely on custom scripting connected to NetSuite workflows.

The exact migration requirement depends on the script version, script type, implementation, dependencies and business process involved.

We recommend approaching the migration as an assessment first and a coding exercise second.

1. 1

   Step 1: Create an inventory

   Identify every script and customization that may be affected. Record:

   • Script name
   • Script ID
   • Script type
   • SuiteScript version
   • Deployment
   • Business process
   • Dependencies
   • Integration dependencies
   • Business criticality
   • Current owner
   • Last usage or modification information

   This gives you a complete picture before any code is changed.

2. 2

   Step 2: Identify business-critical scripts

   Not every script deserves the same priority. A script supporting a critical order-to-cash process should be treated differently from an old script that is no longer being used.

   Oracle also recommends prioritizing critical customizations, high-usage scripts, integrations and scripts with complex dependencies.

3. 3

   Step 3: Decide whether to migrate or retire

   This is an important step that is often overlooked. During an assessment, you may discover scripts that are:

   • No longer used
   • Duplicated
   • Replaced by standard NetSuite functionality
   • Associated with an old integration
   • No longer required by the business

   There is little value in spending migration effort on a customization that the business no longer needs. Sometimes the best migration is to retire the customization.

4. 4

   Step 4: Convert or update the scripts

   For SuiteScript 1.0, the migration may involve restructuring the code around SuiteScript 2.1 modules and rewriting portions of the implementation.

   For SuiteScript 2.0 or 2.x, the process may focus more heavily on runtime compatibility, syntax, annotations and testing.

   Each script should be treated according to its actual implementation rather than assuming every migration is identical.

5. 5

   Step 5: Test in Sandbox

   Do not make a large-scale production change without testing. Test:

   • Script execution
   • Entry points
   • Record operations
   • Searches
   • Sublist behaviour
   • Error handling
   • Integrations
   • Governance usage
   • Dependencies
   • Deployment configuration
   • Business-process results

   For critical processes, compare the new SuiteScript 2.1 behaviour with the existing implementation.

6. 6

   Step 6: Deploy in phases

   For larger NetSuite environments, it is generally safer to migrate groups of scripts rather than changing everything simultaneously.

   Start with manageable customizations, validate the results, and then move toward more complex business-critical scripts.

There is no meaningful single price for a SuiteScript migration project. The cost depends on the size and complexity of the NetSuite environment.

For example, migrating ten simple scripts is very different from migrating ten scripts that support:

• Multiple integrations
• Complex workflows
• Custom records
• Large searches
• Transaction processing
• External APIs
• Scheduled automation
• Critical financial processes

A proper assessment should therefore happen before estimating the migration effort.

For companies with a large number of legacy customizations, a SuiteScript migration assessment can help establish:

1. 1.Number of affected scripts
2. 2.Complexity of each script
3. 3.Dependencies
4. 4.Business criticality
5. 5.Required testing
6. 6.Estimated migration effort
7. 7.Recommended migration sequence

Again, there is no universal timeline. A simple SuiteScript 2.0 to 2.1 update can be considerably different from a complex SuiteScript 1.0 rewrite. The timeline can depend on:

• Number of scripts
• Script type
• Code complexity
• Integrations
• Dependencies
• Testing requirements
• Availability of source code
• Sandbox availability
• Business-owner availability for testing

For that reason, we recommend performing an inventory and technical assessment before committing to a migration schedule.

Before the 2028.2 transition, your organization should consider the following checklist:

• Inventory all SuiteScript customizations
• Identify SuiteScript 1.0 scripts
• Identify SuiteScript 2.0 scripts
• Identify scripts using @NApiVersion 2.x
• Identify business-critical customizations
• Identify integrations
• Review script dependencies
• Identify obsolete scripts
• Decide which scripts should be retired
• Plan SuiteScript 1.0 to 2.1 conversions
• Test SuiteScript 2.0/2.x compatibility with 2.1
• Update scripts to @NApiVersion 2.1
• Test in Sandbox
• Validate business processes
• Deploy in phases
• Monitor production after migration
• Maintain documentation for the migrated scripts

If your NetSuite environment contains a large number of custom scripts, waiting until the final release is unlikely to make the project easier.

Migration projects often uncover dependencies that were not obvious when the customization was originally developed. The earlier you identify those dependencies, the more time you have to:

• Understand the existing customization
• Remove obsolete scripts
• Prioritize important business processes
• Test changes
• Resolve compatibility issues
• Schedule production deployments

The objective should not be to rewrite everything immediately.

Know what you have, understand what is affected, and create a controlled migration plan.

At LST Consultancy, we work with NetSuite customizations, SuiteScript development and NetSuite integrations. For organizations preparing for the SuiteScript 2.1 transition, we can help with:

If your organization has been running NetSuite for several years and has accumulated a significant number of custom scripts, the first step is not necessarily rewriting code. The first step is understanding what you have and what will actually be affected.