NetSuite SuiteScript 2.1 upgrade: how to plan it and what to rewrite first

A SuiteScript 2.1 upgrade is no longer optional. Oracle's guide to transitioning to SuiteScript 2.1 says support for SuiteScript 1.0, SuiteScript 2.0, and scripts annotated @NApiVersion 2.0 or @NApiVersion 2.x, is expected to be removed in NetSuite 2028.2. Before that, from 2027.1, SuiteScript 1.0 support covers critical issues only.

The short answer to "what do I rewrite first?" is this: find every legacy script, delete the ones nobody uses, then rewrite your SuiteScript 1.0 scripts in order of business risk. Scheduled scripts that yield, RESTlets used by integrations, and scripts that touch postings or approvals go to the top. Most SuiteScript 2.0 scripts are a smaller job and can come later.

I write all new NetSuite customisation in SuiteScript 2.1, and I maintain and upgrade older 1.0 code for clients. This is the plan I follow.

The SuiteScript 2.1 timeline Oracle has published

Oracle's transition guide sets out four releases:

• 2026.2: SuiteScript 2.1 becomes the standard scripting model for new and existing scripts.
• 2027.1: SuiteScript 1.0 enters end-of-life support, covering critical issues only. For other problems, Oracle will ask you to convert the script to 2.1 first.
• 2028.1: SuiteScript 1.0 scripts can no longer be deployed in new accounts. They remain deployable in existing accounts. SuiteScript 2.0 and 2.x scripts run as 2.1 by default.
• 2028.2: all new and existing scripts must use SuiteScript 2.1.

Release plans can move, so check Oracle's page before you fix dates in a project plan. The practical point is that 2027.1 matters more than 2028.2. After 2027.1, a SuiteScript 1.0 script that breaks in a way Oracle doesn't class as critical may have to be converted before anyone will look at it. That is a poor time to start a rewrite.

The same releases bring the authentication changes I covered in NetSuite TBA to OAuth 2.0 and SOAP to REST. If you have RESTlets or integrations to rework anyway, plan both changes as one project.

Step 1: Build an inventory of legacy scripts

Oracle's guide suggests three ways to find scripts not on 2.1. The quickest is the script list:

1. Go to Customization > Scripting > Scripts.
2. Use the API Version filter to show 1.0, then 2.0, then 2.x.

For something you can share and sort, create a saved search on script records with the criterion API Version is not 2.1, and show Name, ID, Script Type, API Version, Owner and Description. A SuiteAnalytics workbook grouped by API Version or Script Type works too.

Then add the columns that drive the plan. For each script, note:

• What it does, in one line a finance user would understand.
• Whether it still runs. Check its deployments and execution logs. A script with no recent activity is a candidate for retirement, not conversion.
• Who owns it. Some scripts belong to a SuiteApp or a third-party bundle. Those are the vendor's job to upgrade, so ask each vendor for their plan and date.
• What it touches: transactions, approvals, tax, payments, integrations or just a UI field.
• Dependencies: libraries it loads, other scripts on the same record, workflows that call it.

Step 2: Retire before you rewrite

Most accounts that have been live for several years carry scripts nobody remembers writing. Oracle's guidance is to evaluate inactive or obsolete scripts for retirement instead of migration. Every script you remove is one less to convert, test and support.

Be careful with the word "inactive". A script that runs once a year at year-end, or only when a particular subsidiary posts an intercompany journal, can look unused. Confirm with the process owner before you undeploy anything, and keep a copy of the file.

Step 3: Decide what to rewrite first

Oracle recommends starting with scripts that support critical business processes, high-usage scripts, integrations and scripts with complex dependencies. Within that, this is the order I use.

1. Scheduled scripts that yield or set recovery points

SuiteScript 2.1 scheduled scripts have no equivalent of nlapiYieldScript() or nlapiSetRecoveryPoint(). Oracle's script type differences say 2.1 scheduled scripts don't support manual yielding, and a restarted script begins again from the start. For work that needs yielding, Oracle points you to a Map/Reduce script.

That means these scripts aren't a line-by-line conversion. They are a redesign: split the work into stages, make each record safe to process twice, and decide how errors are reported. They take longest, so start them first.

2. RESTlets and integration scripts

RESTlets sit between NetSuite and other systems, so a failure stops data moving. If the integration also uses TBA or NLAuth, the authentication needs to change too. I built the Cape.io integration between NetSuite and Fortnox in native SuiteScript 2.1, and the lesson carries over: integration code needs proper logging, retries and a test plan agreed with finance. See the Cape.io case study for how that looked across eight subsidiaries.

3. Finance-critical user event and workflow action scripts

Next come scripts on transactions: GL impact, approval routing, vendor bank detail controls, tax fields, intercompany logic. A subtle change here may not throw an error. It may just post a different amount.

4. Client scripts, Suitelets and portlets

These affect what users see. Errors are usually obvious and quick to spot in testing, so they can follow the server-side work.

5. SuiteScript 2.0 and 2.x scripts

These come last because there is a shortcut for many of them. Under Setup > Company > Preferences > General Preferences, Oracle provides two account-level preferences: Execute SuiteScript 2.0 Server Scripts as 2.1 and Execute SuiteScript 2.x Server Scripts as 2.1. They run server scripts on the 2.1 runtime without changing the file, and you can switch them back at any time. Use them in sandbox to see which scripts work unchanged, then update the annotation.

Two limits apply. The preferences cover server scripts only, and there is no equivalent for SuiteScript 1.0. And SuiteScript 2.1 runs on a different engine, so some behaviour changes. Oracle lists differences between 2.0 and 2.1 including error object properties, parseInt, date formatting, strict mode and RESTlet return types.

What changes when you convert SuiteScript 1.0

A SuiteScript 1.0 script can't be fixed by changing a tag. NetSuite doesn't support calling SuiteScript 1.0 APIs from a 2.x script, so every nlapi function and nlobj object has to be replaced with the matching N/ module. Oracle's SuiteScript 1.0 to 2.1 API map is the reference. Expect these changes:

• Structure. Global functions become an AMD module with define, and each entry point receives a single context object.
• Arguments. 2.1 methods take one options object, and parameter names sometimes differ.
• Subrecords. Addresses and other subrecords work differently. You don't save them separately; NetSuite saves them with the parent record.
• APIs with no direct equivalent. Oracle lists some, such as the date-time value functions (use N/format) and nlapiAddDays (use standard JavaScript dates).
• Reserved names. log and util are reserved in 2.1. Oracle notes that a 1.0 variable with either name causes an error if 1.0 and 2.1 scripts run on the same record. That matters during a phased upgrade, when old and new scripts sit side by side.

Using AI to convert scripts, safely

Oracle now publishes a SuiteScript upgrade agent skill, netsuite-suitescript-upgrade, that can analyse, convert, explain and validate legacy scripts. It's a useful first draft and a good way to size the work.

Oracle's own warnings are worth repeating. Validation is a static check, not a substitute for functional testing. Review entry points, dependencies, script IDs and deployment behaviour, and don't change production behaviour just because a conversion completed without errors. Oracle flags date, time zone, subrecord, search, error handling and sublist indexing as areas to check by hand.

Test and release in batches

For each converted script, run it in sandbox against the same records as the original and compare the results: field values, GL lines, emails sent, records created. Then release a few scripts at a time, outside month-end, and watch the execution logs before the next batch. Oracle recommends the same phased approach.

After go-live, make sure each release is tested too. A release readiness check runs your scripts against the release preview before each upgrade, which matters more as 2028 approaches.

If you would rather hand over the inventory and rewrite, my NetSuite customisation and SuiteScript development service covers it, or you can book a call to talk it through.

Want a ranked list of your legacy scripts and a fixed price to upgrade them? The SuiteScript 2.1 and OAuth 2.0 Upgrade starts with a free inventory.