SuiteScript 2.1 Migration: The Timeline and the 2.x Trap

If your account still runs any 1.0, 2.0 or 2.x script, you have probably already seen this at the top of your NetSuite dashboard:

Update Needed: Update Scripts to SuiteScript 2.1

One or more scripts in this account use SuiteScript 1.0, 2.0, or 2.x Scripts using these versions will stop working in NetSuite 2028.2. To ensure compatibility, convert your scripts to SuiteScript 2.1 as soon as possible. For details on removal timelines and next steps, see the help topic Transitioning to SuiteScript 2.1.

That help topic sits behind a NetSuite login, which is part of why the message is hard to act on: the detail you need to size the work is not on the open web.

Two years sounds like plenty of time. It is not, for a reason the banner does not mention: the runtime under your existing scripts changes in 2028.1, one release before the deadline, whether or not you have done anything.

Here is what Oracle has actually scheduled, what changes when your scripts execute under 2.1, and how to find out which of your scripts are affected.

A note on sourcing. The timeline below comes from Oracle's SuiteAnswers article 1047412, SuiteScript 2.1 Required for All Custom Scripts in NetSuite 2028.2, last updated September 16, 2026. SuiteAnswers requires a NetSuite login, so we cite it by answer ID — the article is the primary source, not the dashboard banner. The behavioral differences come from answer 92821 and its child articles, last updated March 9, 2026. We will update this post if Oracle revises them.

The timeline, release by release

Oracle's framing is "gradual removal of SuiteScript 1.0, 2.0, and 2.x." Three cohorts, one destination.

The date that actually matters is 2028.1

2028.2 is when the exit is closed. 2028.1 is when the floor moves.

In 2028.1, scripts annotated @NApiVersion 2.0 and @NApiVersion 2.x execute on the 2.1 runtime by default. Nobody has to redeploy them, and nobody has to approve it. Code nobody has opened since it was deployed starts running on a different engine.

That is survivable, and Oracle built a way back: the account preference can be switched to run those scripts as 2.0 again while you fix what broke. But two things have to be true for that escape hatch to matter. You have to notice the breakage, and you have to know which scripts are affected before month-end.

There is a second date worth marking. If you still run SuiteScript 1.0, 2027.1 — the next release after this one — is when support narrows to critical issues only. After that, a non-critical bug in a 1.0 script comes with a prerequisite: convert it to 2.1 first.

Your @NApiVersion 2.x scripts are SuiteScript 2.0

This is the part that changes how big the job looks.

Plenty of teams write 2.x in the JSDoc tag with the reasonable assumption that it means "the current 2 series," the way a caret works in npm. It does not. Oracle:

Currently, by default, a value of 2.x for the @NApiVersion JSDoc tag will resolve to 2.0 when the script is uploaded and executed. This means that all scripts that include @NApiVersion 2.x are executed as SuiteScript 2.0 scripts.

So 2.x is not a third version, and it is not a moving target that has quietly kept you current. It is an alias for 2.0. Every 2.x script in your account is in scope for this migration, which is why the banner names all three values.

/**
 * @NApiVersion 2.x        <- runs as 2.0 today, as 2.1 from 2028.1
 * @NScriptType UserEventScript
 */
 
/**
 * @NApiVersion 2.1        <- the only annotation that is finished
 * @NScriptType UserEventScript
 */

How to inventory what you have

The Script record carries two fields, and reading only one of them will give you a wrong answer.

API Version shows the version specified in the script file. Oracle is explicit that it always shows a specific version: a script annotated 2.x reports as 2.0 here. Useful for finding work, useless for confirming what is executing.

Execute As Version shows the version actually processing the script. It only appears on the record when the Execute SuiteScript 2.x Server Scripts As preference is set to 2.1, and Oracle calls it the only indication that a script is being executed as 2.1. List views — scripts, deployments, scripted records — keep showing the original API Version regardless.

Practically, that means a saved search on the Script record filtered by API Version tells you how much code is annotated 1.0 or 2.0, with every 2.x script folded into the 2.0 bucket, and tells you nothing about what the preference is doing. Capture both fields.

The preferences live at Setup > Company > Preferences > General Preferences, and there are two of them — one for 2.x scripts and one for 2.0 scripts — so you can test the two cohorts separately.

Oracle's recommended sequence is the conservative one, and it is worth following in order:

1. Identify your 2.x and 2.0 scripts.
2. Switch the company preference to 2.1 in a test account or Release Preview, not production.
3. Exercise the scripts. If they behave, update the annotation to @NApiVersion 2.1.
4. If one misbehaves, switch the preference back while you fix it — then update the annotation. The preference is a testing tool, not a destination. Leaving it on and never touching the JSDoc tag means you pass 2028.2 with annotations that still say 2.0.
5. Retire anything inactive, obsolete, or duplicated. The cheapest script to migrate is the one you delete.

What actually changes when a script runs as 2.1

SuiteScript 2.0 runs ECMAScript 5.1. SuiteScript 2.1 runs ECMAScript 2023 on a different runtime engine. Oracle documents fourteen behavioral differences. They split into two groups, and the split matters: one group fails loudly at upload or execution, the other changes results quietly.

Fails loudly

• Reserved words as identifiers. ECMAScript 2023 reserves words that 5.1 did not. var extends = 1; or a parameter named extends parses fine in 2.0 and throws a syntax error in 2.1. The same applies to any other word reserved in a newer edition.
• for each...in. Removed from the standard years ago, accepted by 2.0, a SyntaxError in 2.1.
• Conditional catch blocks. catch (e if e instanceof TypeError) was never standard. 2.0 runs it; 2.1 throws a SyntaxError.
• Strict mode. Assigning to an undeclared variable executes without complaint in 2.0. In 2.1 you get ReferenceError: x is not defined.
• Reassigning a const. In 2.0 the assignment silently does nothing and the script continues. In 2.1 it stops with TypeError: Assignment to constant variable.
• toSource(). Obsolete, tolerated by 2.0, an error in 2.1.
• Invalid JSON. Trailing commas — JSON.parse('{"mykey" : 1, }') — parse successfully in 2.0 and throw in 2.1. Error text and type differ too, which matters if you match on message strings.

Changes quietly

These are the ones that survive a smoke test and surface a month later in someone's report.

• Decimals with trailing zeros. record.setValue('memo', 616.00) stores a double in 2.0 and an integer in 2.1. Values without trailing zeros stay doubles in both.
• parseInt. Oracle's own example: parseInt('08') yields no value in 2.0 and 8 in 2.1.
• Dates to local strings. The default format changes from long to short: December 21, 2012 becomes 2012-12-21. Extra formatting options passed in are ignored in both versions.
• RESTlet POST responses. 2.0 adds an internal JSON.stringify() to whatever your post() returns; 2.1 does not. A post() that returns JSON.stringify("flower") — already 8 characters — reaches the caller as 12 characters in 2.0, because NetSuite stringifies it again, and as the original 8 in 2.1. Any consumer that parses the response twice, or measures length, changes behavior.
• RESTlet return types. With Content-Type: application/json, 2.0 converts the response to a string; 2.1 returns an object. If the caller is an integration you do not own, this is the one to check first.
• Error objects. JSON.stringify() on an Error created with an argument includes message in 2.0 and returns {} in 2.1, because 2.1 only serializes enumerable properties. Logging and alerting built on stringified errors goes blank rather than failing.

New in 2.1, and the limits

N/llm, N/pgp, and N/crypto/random (in server scripts) are 2.1-only. Server-side async, await, and promise work, but only in N/http, N/https, N/llm, N/query, N/search, and N/transaction — N/record is not on that list, so a plan to modernize record operations with async/await will not get far. Debugging also moves from the SuiteScript Debugger to the browser debugger.

What Oracle has not said

Worth being precise about the gaps, because they affect planning:

• Bundled and SuiteApp scripts. The article addresses scripts you own. It says nothing about code installed from a bundle or a SuiteApp that you cannot edit. If a vendor's script is annotated 2.0, the remediation is theirs, and the only lever you have is asking them for a date. Start asking now rather than in 2028.
• No intermediate enforcement. Nothing in the timeline blocks creating new 1.0 or 2.0 scripts before 2028.1, beyond the new-account restriction. The pressure between now and then is support, not enforcement.
• Exact upgrade dates. NetSuite ships two releases a year and upgrades accounts on a rolling schedule, so "2028.2" is a window, not a day. Your account's date will come from your own release schedule.

A sane order of work

You do not need a migration project this quarter. You need an inventory this quarter.

1. Count. Scripts by annotation, with 2.x and 2.0 separated, and deployments per script. This number decides whether the rest is a sprint or a program.
2. Delete. Inactive, duplicated, and superseded scripts. This is the only step that reduces the total.
3. Classify by blast radius. RESTlets consumed by systems you do not control, and scripts that write numeric or date values, are the ones where 2.1 changes results rather than throwing. They get tested properly. A Suitelet that renders an internal form does not.
4. Test in Release Preview with the preference flipped, the cohorts separated, and real volume.
5. Flip annotations as you verify, script by script. The annotation is the deliverable; the preference is scaffolding.
6. Ask your vendors for their 2.1 date, in writing.

The teams that will be fine in 2028.1 are the ones that did the counting in 2026.